Running Qoder CLI in Scripts

Overview

Headless (non-interactive) mode allows Qoder CLI to run without an interactive interface—it receives a prompt, executes the task, outputs the result to standard output, and exits. It is ideal for embedding Qoder into Shell scripts, automation workflows, and CI/CD Pipelines. To enter Headless mode, add the --print flag (short form -p):

qodercli -p "Explain the architecture of this code repository"

Since there is no one around to confirm, permissions in Headless mode must be pre-configured—any operation that would normally require a pop-up confirmation will be automatically denied in plain text Headless mode. See Permissions for details.

Basic Usage

Pass the prompt as an argument and add -p:

qodercli -p "Generate a commit message for this change"

You can also pass the prompt via standard input:

echo "Summarize all code changes from yesterday" | qodercli -p

Capture the output in a script:

result=$(qodercli -p "List all exported functions in the src directory")
echo "$result"

Output Format

Use --output-format (short form -o) to specify the output format. The default is text:

Format	Description	Use Case
`text`	Plain text result (default)	Direct reading, simple scripts
`json`	Single JSON Object containing the result and Metadata	Programmatic parsing of the final result
`stream-json`	Line-by-line JSON Message Stream	Real-time consumption of intermediate processes

Example:

# Plain text (default)
qodercli -p "Explain the purpose of main.ts"

# JSON: for easy script parsing
qodercli -p "Explain the purpose of main.ts" --output-format json

# Stream JSON: consume message streams in real time
qodercli -p "Refactor the utils module" --output-format stream-json

The Input Format can be specified using --input-format, supporting text and stream-json. When using stream-json input, you can continuously send Structured Messages via standard input.

Common Flags

Headless mode is often used in combination with the following flags:

Flag	Description
`-p, --print`	Print the response and exit (non-interactive)
`-o, --output-format <format>`	Output Format: text / json / stream-json
`--input-format <format>`	Input Format: text / stream-json
`--max-turns <count>`	Limit the maximum Conversation Turns for a single query
`--permission-mode <mode>`	Set the permission mode
`--allowed-tools <tool>`	Allow only specified tools
`--disallowed-tools <tool>`	Deny specified tools
`-m, --model <model>`	Specify the Model
`--session-id <id>`	Use the specified session ID
`-w, --cwd <dir>`	Switch the working directory before startup

For a complete list of flags, see CLI Startup Arguments Reference.

Permission Control

Since there is no interactive confirmation in Headless mode, you need to pre-determine which operations can be executed automatically using permission flags:

# File edits are auto-approved, shell commands are still rejected
qodercli -p "Refactor utils module" --permission-mode accept_edits

# Allow only specific tools
qodercli -p "Check status" --allowed-tools 'Read,Bash(git status)'

# Allow all (for trusted scenarios only)
qodercli -p "Run database migration" --yolo

In plain text Headless mode, any operation that "requires confirmation" defaults to deny. If driven by a Host Application via the stream-json protocol (e.g., Agent SDK), confirmation requests are forwarded to the Host Application for decision. See "Consumption methods of ask in different runtime environments" in Permissions.
Use --permission-mode accept_edits to automatically approve safe file edits within the working directory.
Use --yolo (equivalent to --permission-mode bypass_permissions) to skip all confirmations. This is only recommended for use in fully trusted environments.

For details on the behavior of each permission mode, see Permissions.

CI/CD Example

In a pipeline, authentication is typically completed first via Environment Variables before running in Headless mode:

export QODER_PERSONAL_ACCESS_TOKEN="your_token"

qodercli -p "Review these changes and list potential issues" \
  --output-format json \
  --permission-mode accept_edits \
  --max-turns 20

See Sign-in and Authentication for authentication methods. Set the output format to json to make it easier for subsequent pipeline steps to parse Qoder's results.