exec.md

Non-interactive mode

Use Kay in non-interactive mode to automate common workflows.

kay exec "count the total number of lines of code in this project"

In non-interactive mode, Kay does not ask for command or edit approvals. By default it runs in read-only mode, so it cannot edit files or run commands that require network access.

Use kay exec --full-auto to allow file edits. Use kay exec --sandbox danger-full-access to allow edits and networked commands.

Default output mode

By default, Kay streams its activity to stderr and only writes the final message from the agent to stdout. This makes it easier to pipe kay exec into another tool without extra filtering.

To write the output of kay exec to a file, in addition to using a shell redirect like >, there is also a dedicated flag to specify an output file: -o/--output-last-message.

JSON output mode

kay exec supports a --json mode that streams events to stdout as JSON Lines (JSONL) while the agent runs.

Supported event types:

• thread.started - when a thread is started or resumed.
• turn.started - when a turn starts. A turn encompasses all events between the user message and the assistant response.
• turn.completed - when a turn completes; includes token usage.
• turn.failed - when a turn fails; includes error details.
• item.started/item.updated/item.completed - when a thread item is added/updated/completed.

Supported item types:

• assistant_message - assistant message.
• reasoning - a summary of the assistant's thinking.
• command_execution - assistant executing a command.
• file_change - assistant making file changes.
• mcp_tool_call - assistant calling an MCP tool.
• web_search - assistant performing a web search.

Typically, an assistant_message is added at the end of the turn.

Sample output:

{"type":"thread.started","thread_id":"0199a213-81c0-7800-8aa1-bbab2a035a53"}
{"type":"turn.started"}
{"type":"item.completed","item":{"id":"item_0","item_type":"reasoning","text":"**Searching for README files**"}}
{"type":"item.started","item":{"id":"item_1","item_type":"command_execution","command":"bash -lc ls","aggregated_output":"","status":"in_progress"}}
{"type":"item.completed","item":{"id":"item_1","item_type":"command_execution","command":"bash -lc ls","aggregated_output":"AGENTS.md\nCHANGELOG.md\nREADME.md\nkay-rs\ncodex-rs\ncodex-cli\ndocs\nscripts\nsdk\n","exit_code":0,"status":"completed"}}
{"type":"item.completed","item":{"id":"item_2","item_type":"reasoning","text":"**Checking repository root for README**"}}
{"type":"item.completed","item":{"id":"item_3","item_type":"assistant_message","text":"Yep — there’s a `README.md` in the repository root."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122}}

Structured output

By default, the agent responds with natural language. Use --output-schema to provide a JSON Schema that defines the expected JSON output.

The JSON Schema must follow the strict schema rules. Schema files are capped at 8 KiB so a large schema cannot crowd out the rest of the model-visible turn context.

Sample schema:

{
  "type": "object",
  "properties": {
    "project_name": { "type": "string" },
    "programming_languages": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["project_name", "programming_languages"],
  "additionalProperties": false
}

kay exec "Extract details of the project" --output-schema ~/schema.json
...

{"project_name":"Kay CLI","programming_languages":["Rust","TypeScript","Shell"]}

Combine --output-schema with -o to only print the final JSON output. You can also pass a file path to -o to save the JSON output to a file.

Provider behavior varies by wire protocol. Responses API models receive native structured-output settings. OpenAI-compatible Chat Completions providers use native response_format only for no-tool turns when the model family supports it; MiMo-family Chat Completions turns use the same bounded final-output contract as system guidance so direct Xiaomi and OpenCode Go MiMo share one compatibility path.

MiMo-family turns also get a final-output repair pass. If a MiMo model emits a progress assistant message where the schema requires JSON, Kay prompts the model to continue with tools or return the contracted JSON instead of treating that progress message as successful completion.

Git repository requirement

Kay requires a Git repository to avoid destructive changes. To disable this check, use kay exec --skip-git-repo-check.

Resuming non-interactive sessions

Resume a previous non-interactive session with kay exec resume <SESSION_ID> or kay exec resume --last. This preserves conversation context so you can ask follow-up questions or give new tasks to the agent.

kay exec "Review the change, look for use-after-free issues"
kay exec resume --last "Fix use-after-free issues"

Only the conversation context is preserved; you must still provide flags to customize Kay behavior.

kay exec --model gpt-5.1 --json "Review the change, look for use-after-free issues"
kay exec --model gpt-5.1 --json resume --last "Fix use-after-free issues"

Time limits and final status

--max-seconds stops a run when the wall-clock budget is exhausted. Kay writes STATUS: BLOCKED to --output-last-message (when configured) and exits with code 1. Host wrappers that use timeout/gtimeout may still surface exit code 124 after SIGTERM; Kay flushes STATUS: BLOCKED to the last-message file on SIGTERM so partial work remains salvageable for Sidekick verification.

Delegated prompts that require a final status line (for example Final message must include STATUS: SUCCESS or STATUS: BLOCKED) are enforced at process exit: Kay returns exit code 1 when the last agent message does not satisfy the contract. When the model emits STATUS: mid-message, Kay salvages the status block to the message prefix; when status is still missing, Kay submits one repair turn requesting a contract-compliant final status block before exiting.

Authentication

By default, kay exec uses the same authentication method as the TUI and VSCode extension. You can override the API key by setting the CODEX_API_KEY environment variable.

CODEX_API_KEY=your-api-key-here kay exec "Fix merge conflict"

NOTE: CODEX_API_KEY is only supported in kay exec.