Run a single prompt
Send one message with afk chat, read input from a pipe, and collect text or structured output.
afk chat sends one message, lets the agent use tools to complete it, prints the response, and exits. Use it for a quick answer, a shell script, or a CI job without opening the interactive REPL. afk c is an alias.
afk chat "Summarize the last 10 git commits. Do not change files."Pipe a prompt
Put the instruction and input in the same stream
{ printf 'Summarize these changes:\n\n'; git diff; } | afk chat -Or read a complete prompt from a file
afk chat - < prompt.txtYou can omit the message argument when stdin is piped: cat prompt.txt | afk chat.
A positional message other than - takes precedence over stdin. For example, cat error.log | afk chat "Explain this" sends only Explain this, not the file contents. Combine the instruction and data in stdin instead.
Input is limited to 10 MiB (10,485,760 bytes). Trailing newline characters are removed. Missing input, empty input, and whitespace-only input are errors. Passing - without a pipe or redirected stdin is also an error.
Common options
| Option | Use |
|---|---|
--model opus | Choose a model or configured alias. |
--max-turns 20 | Set the conversation turn limit. The chat default is 10. |
--format json | Print the final response as a JSON object. |
--format stream-json | Emit newline-delimited events during the run. |
--max-budget-usd 2.00 | Set the session cost ceiling in USD. |
--permission-mode default | Override the configured permission mode. |
--mcp-config tools.json | Merge an additional MCP configuration at highest priority. |
--worktree | Run in a separate git checkout. |
--worktree-base HEAD | Base that checkout on your current local commit. |
--continue | Continue the newest saved session. |
--resume <id> | Continue a particular saved session. |
--session-id <uuid> | Create a new session with a specific unused UUID. |
--post github,telegram | Publish the final response to those destinations. |
--post-pr <ref> | Select the PR for GitHub publishing instead of the current branch's PR. |
See the CLI reference for provider selection, thinking, effort, output-token limits, and other options. --stream is currently reserved and has no effect; use --format stream-json for streaming output.
A one-shot run is not a sandbox. It can execute tools and modify files under the configured permissions. Publishing with --post sends content outside your machine. A publishing failure is reported on stderr but does not by itself fail the completed chat run.
Choose an output format
| Format | Output |
|---|---|
text (default) | Terminal-rendered Markdown, followed by available duration, cost, and token totals. |
json | One final object with success, model, and message, plus available timestamp, cost, duration, token, and trace identity fields. |
stream-json | One JSON event per line, including content chunks, completion, progress, and errors. |
afk chat "Summarize this repository. Do not change files." --format json > response.json
afk chat "Run the tests and explain any failures." --format stream-json | tee run.ndjsonJSON metadata is conditional: do not assume that every provider supplies costs, token counts, or a session identifier. sessionId, witnessLabel, and tracePath, when present, let automation locate the matching session and trace without searching for the newest file.
See headless output for event schemas, parsing recipes, stdout/stderr handling, and pipeline exit handling.
Save and continue a session
Create a saved conversation with an unused UUID, then continue it:
SESSION_ID="$(node -p 'crypto.randomUUID()')"
afk chat "Inspect the project and summarize its architecture." --session-id "$SESSION_ID"
afk chat "Which modules would you test first?" --resume "$SESSION_ID"After a completed turn, sessions created with --session-id or resumed with --resume or --continue are saved, and a continuation command is printed to stderr. Do not rely on an ordinary one-shot run creating the same saved-session entry.
--resume, --continue, and --session-id are mutually exclusive. An unknown resume target, an invalid UUID, or a UUID already used by a saved session is an error. A resumed session uses its stored model.
--continue currently selects the newest saved session from the shared session store, not a session filtered to your current directory. Use --resume when multiple projects or surfaces are active.
Isolate file changes in a worktree
afk chat "Fix the failing tests and verify the fix." --worktree --worktree-base HEAD--worktree accepts an optional branch name; without one, AFK chooses a name. Without a base override, AFK normally uses the remote's default branch, fetched fresh. Use --worktree-base HEAD when you want your current local commit instead.
Cleanup removes a clean checkout and attempts to delete its branch. A checkout with uncommitted changes or protected ignored local state is preserved, with its location printed. A worktree isolates git changes, not tool access or credentials. See worktrees for the full lifecycle.
Exit status
| Code | Meaning |
|---|---|
0 | The command completed without a reported error. |
1 | Input validation, authentication, budget, hook, network, or other general failure. A streamed error event also sets this code. |
124 | A thrown timeout classified by the CLI error handler. |
A failure emitted as a stream event uses 1, even if its underlying cause is a timeout. Do not use exit status alone as evidence that the agent's changes passed verification; inspect the response and relevant test results.