Skip to content
Browse documentation
cli

Commands and structured output

Look up commands, execution flags, JSON results, MCP formats, and exit codes.

Find a command

Check your installed version, then ask for help on any command:

bash
smoothie --version
smoothie help --format json
smoothie help mcp serve --format json
Frameworkframework releases, framework acquire, framework verify, framework use, framework recover
Recipesrecipe list, recipe show, recipe create
Projectsproject context, project check, project verify, project adopt, project build, project connect, project deploy, project status, project preview, init, doctor
Skillsskills install
Contextcontext search, context read
Local toolstool list, tool show, tool invoke
MCPmcp serve, mcp inspect, mcp review, mcp probe, mcp add, mcp edit, mcp remove, mcp approve, mcp revoke, mcp host-config
Local embedding assetsembedding setup, embedding status, embedding remove
Noticeslicenses

Installed help lists that binary's exact flags. Operations accept --help and --format human|json; human is the default. --version stands alone. Unknown flags, including retired --verbose/--quiet, are errors. CLI, Framework, and protocol versions are separate.

Preview or execute

Execution controls depend on the command. Do not add --run to every operation.

framework use / recipe createPreview: --dry-run. Apply: unchanged inputs with --expect-plan. --install is separate; --yes does not enable it.
skills install / MCP configuration and approvalPlan by default. Apply with --run --expect-plan and that operation's planId or planDigest.
Native checks, probes, previews, inference--run enables execution. Check the command's plan/revision requirements first.
Acquisition and metadata creationacquire, init, and project adopt can write without --run. Not every command plans by default.
Interactive MCP setupOnly mcp add/approve --interactive prompt. They need a human terminal, not JSON/noninteractive apply flags.

Read JSON results

For scripts and agents, use --format json and check fields rather than parsing summary text.

schemaVersion, cliVersion, operationIdentify the result schema, executable, and requested operation.
status, subject, summarystatus: success, blocked, failed, or cancelled. subject identifies scope; summary is prose, not a parser key.
dataThe operation's result, or null. Validate its own schema too.
diagnosticsError codes, messages, and remediation. Branch on codes, not wording.
effectsFilesystem/network/process effects: planned, completed, failed, or unknown. Do not automatically retry unknown effects.
checksNative results or null: planned/passed/failed/blocked/skipped/cancelled, with execution and exit details.
nextActionsSuggested labels/argv. They do not execute anything or grant permission.

stdout contains one result, at most 4 MiB including its newline. Progress goes to stderr; child logs may contain secrets, so do not share them automatically. Missing or malformed output is not success.

MCP protocol

MCP stdio instead carries protocol messages, not a one-shot CLI result. Smoothie uses protocol version 2025-11-25 with bounded tool/lifecycle and cancellation support, not every MCP feature. Keep stdout free of shell banners; diagnostics use stderr.

Searchresult.structuredContent uses smoothie.mcp-search/v4. Compatibility text carries the same JSON.
InvocationstructuredContent uses smoothie.mcp-invocation/v2. Inspect status, data, and diagnostics.
Reference readsUp to 8 KiB per page; CLI pages allow 64 KiB. Pass both expected revisions and nextCursor on the same connection.

Reconnect? Search again and restart paged reads. A tool's input/output schema belongs to that tool, not the terminal envelope. See tool discovery for the call sequence.

Discovery and tool calls

Coding agents make these calls for you. These tools/call payloads are for integration authors tracing the search-to-invocation flow. They use --exposure search; native exposure uses tools/list and named tools/call instead.

Search approved tools
{
  "name": "search_capabilities",
  "arguments": {
    "query": "Read a task's current status by its ID",
    "kind": "tool",
    "limit": 5
  }
}

Inspect result.structuredContent (smoothie.mcp-search/v4): status, data.readiness, data.complete, and diagnostics. Tools appear in data.results.tools.groups; each group has sourceId, sourceRevision, and hits containing id, description, inputSchema, and score. limit spans all tool groups. complete describes source coverage, not recall.

idCopy the selected hit.id exactly.
expectedSourceRevisionCopy group.sourceRevision, not a model digest, indexIdentity, or document revision.
argumentsSupply an object valid against hit.inputSchema. describe_tool is optional; search includes the full schema.

This is a template, not a built-in task API. Replace both placeholders with actual search values. Use taskId only if the selected inputSchema accepts it:

Invoke the selected tool
{
  "name": "invoke_tool",
  "arguments": {
    "id": "<hit.id>",
    "expectedSourceRevision": "<group.sourceRevision>",
    "arguments": { "taskId": "task-42" }
  }
}

Invocation uses smoothie.mcp-invocation/v2. Inspect status, diagnostics, and data: effectState, cleanupFailed, and result; local calls also report started/processStatus, upstream calls dispatched/outcome. An allowed attempt is consumed before dispatch. Never automatically retry an uncertain invocation; a reply is not proof of business success.

readyInspect coverage, diagnostics, and contracts before invoking.
preparingIndexing is running. Wait and retry discovery within a bounded policy.
staleHits are withheld. Search requests a bounded refresh under unchanged startup grants; rediscover when ready.
unavailableCheck executable backend, verified assets, and diagnostics before reconnecting.
failed or cancelledReport the diagnostic. Failed/cancelled preparation or refresh requires an intentional restart.

Results/indexIdentity can be null when not ready. There is no silent fallback to BM25. connection_status observes upstream availability/allowances, not embedding readiness. Source changes do not renew permission; failed query results do not prove a failed index.

External-tool automation options

For the interactive walkthrough, use Connect external tools. Automation uses these options instead:

add / edit--from selects one reviewed connection-entry JSON file. remove takes no --from.
approveSupply --review, exact --allow-upstream-tool pins, and --max-calls.
ApplyPlan first, then --run --expect-plan <data.planDigest> with unchanged inputs.
ConfigurationDefault: .smoothie/upstreams.local.json under --project. --upstreams selects an absolute alternative, without merging files.

Preserve unrelated entries and keep local config/locks out of Git. Declarations contain environment variable names, never secrets. Terminal access alone is not consent to approve.

Exit codes

0The requested operation succeeded. Check what it actually verified.
2Invalid command or arguments.
3Blocked prerequisite.
4Failed metadata/native check or write/install effect.
130Cancellation.

Native exit codes stay in check records. A successful plan is not execution, and a successful upload is not app health. Continue with CI and troubleshooting or Skills installation.