ExecuteSpec CLI

Command-line client for ExecuteSpec.

Use it to chat from any folder, submit specs, watch runs, approve plan gates, inspect run status, and run local-hands workflows against a trusted working tree. The CLI is intentionally thin: the agent loop, prompts, model routing, scoring, billing, and durable run history stay server-side.

Install

npm install -g executespec

executespec is the canonical CLI package. The former @executespec/cli package is deprecated.

Platform and release posture, including Homebrew, Windows PowerShell, update checks, and publish gates, is tracked in the CLI platform release guide.

The package installs all local CLI entrypoints:

executespec
es
eslocal

Start Chat

Run this from any project folder:

executespec

If you are not signed in, the CLI starts the web-login flow. After login, plain text is treated as chat. Slash commands are optional.

Interactive TUI behavior:

• A fresh session opens with an actionable next-step card: example requests, the most useful session commands, and the active workspace are visible before the first turn. The transcript remains the primary surface; this guidance disappears as conversation activity arrives.
• Esc cancels the current drawer, prompt, proposal, or draft; it does not exit the app. Use /exit to leave.
• Ctrl-G opens the current composer draft in $VISUAL (falling back to $EDITOR) and safely returns the edited text to the prompt.
• Unknown slash commands are handled locally with suggestions. They are not sent as model chat turns.
• Prefix a command with ! (for example, !npm test) to request one local shell command from the TUI. It always goes through the normal shell safety guard and interactive permission prompt; the marker never grants trust or sends the command to the backend.
• Repo-level questions can attach bounded read-only folder context after an explicit prompt. Direct local reads such as file/list/search answers stay local when possible.
• /clear removes the local transcript and resume record and asks the server to clear the durable session transcript while retaining the usage ledger. If the server is unavailable, the CLI reports that the reset was local-only.
• Assistant replies keep a plain-text-safe Markdown subset in the transcript: headings and bullets retain semantic markers, and fenced code blocks get bounded language/gutter framing without a parser dependency. Unknown Markdown is preserved verbatim.
• Live run panes show a semantic progress narrative (status, changed, progress, approval, and attention) instead of raw backend telemetry. The complete event stream remains available through /tasks logs <run-id>, so the waiting surface stays readable without losing forensic detail.

Accessibility boundary

Use executespec --accessible (or --plain) for a no-decoration readline surface that works with screen readers. The native OpenTUI renderer has no portable native Terminal.app accessibility tree; its dynamic state is visual terminal output only. Integrations that embed the renderer can opt into the deterministic plain-text AnnouncementSink for permission, plan, provider/model, verification, and completion transitions. This is an announcement channel, not proof of native Terminal Accessibility API support.

Common Commands

executespec --help
executespec config get host
executespec config set host https://dev.executespec.ai
executespec auth login
executespec run submit "add a /health endpoint with tests" --watch
executespec -p "describe this screenshot" --image assets/screen.png --format json
executespec commands list --scope all
executespec commands path --scope user

Headless --image <path> and interactive image mentions upload raw bytes through the authenticated agent-session attachment endpoint after cwd, symlink, MIME, and 10 MB checks. The backend/provider still decides whether the selected model can inspect the image; the CLI never runs local vision/OCR.

Custom slash commands live in .executespec/commands/*.md or .executespec/commands/*.toml for a project and <configDir>/commands/*.md or <configDir>/commands/*.toml for user commands. Project commands override user commands by name, and effective commands are discoverable through the native OpenTUI palette and readline Tab completion.

Default Host

The default backend is:

https://dev.executespec.ai

Override order:

1. --host
2. EXECUTESPEC_HOST
3. stored config
4. built-in default

Safety Model

Remote runs execute through the ExecuteSpec backend and do not mutate your local working tree. Local-hands mode is separate and requires explicit local context, workspace trust, and guardrails before file or shell tools are used. Treat the default posture as policy/approval based unless sandbox status reports an active hard-sandbox provider.

executespec doctor --validate-backend-capability performs an explicit read-only backend probe. On newer backends it reads /api/v3/client-capabilities so the CLI can show whether local-hands is supported, enabled, PAT-authenticated, and ready before a local tool pump is started. The same probe reports managed-AI credit state from backend entitlements. Unlimited BYOK, Team, and Enterprise credit tiers are rendered as unlimited/ungated rather than 0 / 0 credits.

License

Proprietary. All rights reserved.