Skip to main content

shaft-cli command line

shaft-cli is an MCP client and command-line interface to shaft-mcp. It brings the full shaft-mcp tool set to the command line with zero tool-logic duplication, operating in two modes: stateless one-shot commands and a persistent session mode for stateful tools.

Install​

Use the standalone --install-shaft-cli command in Install SHAFT agent tools. It installs shaft-cli and the required shaft-mcp runtime automatically without configuring an MCP client. No local Java or Python is required.

The installer downloads and SHA-256-verifies shaft-cli-<version>.jar from Maven Central, then writes a runnable launcher (shaft-cli on macOS/Linux, shaft-cli.cmd on Windows) plus a shaft-cli.args Java argfile next to it, under the platform's application-data root:

  • Windows: %LOCALAPPDATA%\ShaftHQ\shaft-cli\versions\<version>\
  • macOS: ~/Library/Application Support/ShaftHQ/shaft-cli/versions/<version>/
  • Linux: ${XDG_DATA_HOME:-~/.local/share}/shafthq/shaft-cli/versions/<version>/

shaft-mcp is an internal prerequisite that the standalone installer provides. shaft-cli locates it in this order:

  1. The SHAFT_MCP_JAR environment variable
  2. The installer's versions directory
  3. A sibling ../shaft-mcp/target (development checkout)

Modes​

One-shot mode (default): each command spawns an ephemeral shaft-mcp child process over stdio, runs a single tool call, and exits. Suitable for stateless tools like guide search and doctor analysis.

Session mode: shaft-cli session start launches a persistent shaft-mcp daemon (HTTP on a localhost port) and records the session endpoint to ~/.shaft/cli-session.json. Subsequent commands connect over HTTP, preserving browser and device state across invocations. Commands that need live state (browser, element, capture) fail fast when no session is running, unless --stdio-ok is passed.

Routing: if a live session exists, commands use HTTP; otherwise a one-shot stdio child is spawned.

Commands​

All commands support -h/--help; the root supports -V/--version.

shaft-cli tools [--json] — list all available tools (name and first sentence of description). --json outputs the raw tools/list result.

shaft-cli call <TOOL> [key=value ...] [--args '<json>'] [--json] [--stdio-ok] — invoke any tool by name. Arguments come from repeated key=value pairs (values are coerced: true/false to booleans, integers/decimals to numbers, {...}/[...] to JSON, otherwise strings) and/or --args '{"k":"v"}' (key=value overrides keys from --args). --json outputs the raw JSON-RPC result instead of rendered text.

shaft-cli session start | status | stop — manage the daemon. start prints the port and pid; status prints running — port <port>, pid <pid>, started <iso-8601>.

Curated aliases (same options as call):

  • shaft-cli browser navigate|screenshot|dom|url (session required)
  • shaft-cli element click|type|hover (session required)
  • shaft-cli capture start|stop|status|code (session required)
  • shaft-cli guide search (stateless)
  • shaft-cli doctor analyze|suggest (stateless)

shaft-cli setup ... — diagnose local prerequisites and create an exact, reviewable plan for SHAFT-owned tools. Setup commands run directly and do not require an MCP session. Follow the local infrastructure setup guide for the plan, digest approval, policy options, readiness exit codes, and current provider coverage.

Examples​

shaft-cli tools
# trace_latest — returns recent persisted SHAFT trace indexes from target/shaft-traces
# [...]

shaft-cli session start
# shaft-cli session started on port 12345 (pid 9876).

shaft-cli session status
# running — port 12345, pid 9876, started 2025-12-20T14:30:45Z

shaft-cli call shaft_guide_search query='click element' maxResults=1
# [JSON guide-search result]

shaft-cli guide search query='click element' --stdio-ok
# [guide search works with no session]

shaft-cli call test_plan_explore targetUrl=https://example.test goal='checkout happy path' maxDepth=2
# [Markdown test plans written to specs/]

Exit codes​

  • 0: success
  • 1: tool error, transport error, or --json result with isError
  • 2: unknown alias action