Headless Mode

Run Command Code non-interactively in scripts, CI/CD pipelines, and automation workflows. Headless mode executes a single query, outputs the response to stdout, and exits.

Basic Usage

Use the -p (or --print) flag to run in headless mode:

cmd -p "explain this file"

Info

Always wrap your query in quotes. Unquoted multi-word queries cause argument parsing errors.

Input Methods

Direct Argument

Pass your query directly after the -p flag:

cmd -p "refactor the auth module"

Piped Stdin

Pipe input from another command or file:

echo "explain this error" | cmd -p

cat prompt.txt | cmd -p

Command Code auto-detects piped input when no query argument is provided. If stdin is a TTY and no query is given, it exits with an error.

Permissions

By default, headless mode blocks tools that modify your system — file writes, file edits, and shell commands are denied. This keeps automated runs safe.

To enable all tools, pass --dangerously-skip-permissions:

cmd -p "fix the lint errors" --dangerously-skip-permissions

Tool	Default (no flag)	With `--dangerously-skip-permissions`
File reads, grep, glob	Allowed	Allowed
File edits and writes	Blocked	Allowed
Shell commands	Blocked	Allowed

Warning

Only use --dangerously-skip-permissions in trusted environments. It allows Command Code to modify files and run shell commands without confirmation.

Tool Calls

Headless mode supports multi-turn tool execution. Command Code can read files, search code, and (with permissions) edit files and run commands, just like interactive mode.

The conversation loop runs for up to 10 turns. If the limit is reached, a warning is printed to stderr and the partial response is returned.

Exit Codes

Use exit codes to handle results in scripts and CI/CD:

Code	Meaning	Constant
`0`	Success	`EXIT_SUCCESS`
`1`	General error	`EXIT_ERROR`
`3`	Not authenticated	`EXIT_AUTH_ERROR`
`4`	Permission denied	`EXIT_PERMISSION_DENIED`
`5`	Rate limit exceeded	`EXIT_RATE_LIMITED`
`6`	Network failure	`EXIT_CONNECTION_ERROR`
`7`	API server error (5xx)	`EXIT_SERVER_ERROR`
`130`	Interrupted (SIGINT/SIGTERM)	`EXIT_INTERRUPTED`

Example usage in a script:

cmd -p "check for security issues" --dangerously-skip-permissions
if [ $? -ne 0 ]; then
  echo "Command Code failed"
  exit 1
fi

CI/CD Examples

GitHub Actions

- name: Code review with Command Code
  run: |
    cmd -p "review the changes in this PR" --skip-onboarding
  env:
    COMMANDCODE_API_KEY: ${{ secrets.COMMANDCODE_API_KEY }}

Shell Script

#!/bin/bash
set -e

# Generate docs for changed files
CHANGED=$(git diff --name-only HEAD~1)
echo "Document these changed files: $CHANGED" | cmd -p --skip-onboarding

Piping Output

Headless mode is pipe-friendly. Output goes to stdout, errors and warnings go to stderr:

# Save response to a file
cmd -p "generate a README for this project" > README.md

# Pipe to another command
cmd -p "list all TODO comments" | grep "critical"

# Use in command substitution
SUMMARY=$(cmd -p "summarize this codebase in one paragraph")

Flags useful for headless and automated workflows:

Flag	Description
`-p, --print [query]`	Run in headless mode
`--dangerously-skip-permissions`	Allow file writes and shell commands
`--skip-onboarding`	Skip taste onboarding (for CI/automated runs)
`-t, --trust`	Auto-trust project (skip initial permission prompt)
`--plan`	Start in plan mode (read-only exploration)
`--permission-mode <mode>`	Set permission mode: `standard`, `plan`, `auto-accept`

Limitations

Limitation	Details
Max turns	Up to 10 conversation turns per query (tool calls count as turns)
No interactive prompts	Cannot use slash commands, keyboard shortcuts, or interactive UI
Session scope	Each invocation is a standalone session with no conversation history
Stdin timeout	Piped stdin times out after 30 seconds if no data is received

Next steps

See CLI Reference for the full list of flags and commands
Learn about Interactive Mode for full-featured sessions
Join our Discord community for support

Core Concepts