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:
smoothie --version
smoothie help --format json
smoothie help mcp serve --format jsonInstalled 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.
Read JSON results
For scripts and agents, use --format json and check fields rather than parsing summary text.
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.
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.
{
"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.
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:
{
"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.
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:
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
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.