Run in Scripts - Qoder CN

Overview

Headless (non-interactive) mode lets Qoder CLI CN run without an interactive interface — it takes a prompt, executes the task, writes the result to standard output, and exits. It suits embedding Qoder into shell scripts, automated processes, and CI/CD pipelines. Enter Headless mode by adding --print (short form -p):

qodercn -p "Explain the architecture of this repository"

Since nobody is around to confirm, permissions in Headless mode need to be configured in advance — any operation that would normally pop up a confirmation is automatically denied in plain-text Headless mode. See Permissions and Directory Trust.

Basic usage

Pass the prompt as an argument along with -p:

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

You can also pass the prompt via standard input:

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

Capture the output in a script:

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

Output formats

Specify the output format with --output-format (short form -o); the default is text:

Format	Description	Best for
`text`	Plain-text result (default)	Direct reading, simple scripts
`json`	A single JSON object with the result and metadata	Programmatic parsing of the final result
`stream-json`	A stream of JSON messages emitted one by one	Consuming intermediate progress in real time

Examples:

# Plain text (default)
qodercn -p "Explain what main.ts does"

# JSON: easy for scripts to parse
qodercn -p "Explain what main.ts does" --output-format json

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

The input format can be specified with --input-format, supporting text and stream-json. With stream-json input, you can continuously send structured messages via standard input.

Common flags

These flags are commonly used together with Headless mode:

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 per query
`--permission-mode <mode>`	Set the permission mode
`--allowed-tools <tool>`	Allow only the specified tools
`--disallowed-tools <tool>`	Disallow the specified tools
`-m, --model <model>`	Specify the model
`--session-id <id>`	Use a specific session id
`-w, --cwd <dir>`	Change the working directory before startup

For all flags, see CLI Commands and Flags.

Permission control

There is no interactive confirmation in Headless mode, so use permission flags to decide in advance which operations may run automatically:

# File edits auto-approved; shell commands still denied
qodercn -p "Refactor the utils module" --permission-mode accept_edits

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

# Allow everything (trusted environments only)
qodercn -p "Run the database migration" --yolo

In plain-text Headless mode, any operation that "requires confirmation" is denied by default; when driven by a host program via the stream-json protocol (such as the Agent SDK), confirmation requests are handed to the host program to decide — see "How ask is consumed in different runtime environments" in Permissions and Directory Trust.
Use --permission-mode accept_edits to auto-approve safe file edits within the working directory.
Use --yolo (equivalent to --permission-mode bypass_permissions) to skip all confirmations — recommended only in fully trusted environments.

For the behavior of each permission mode, see Permissions and Directory Trust.

CI/CD example

In a pipeline, authenticate via environment variables first, then run in Headless mode:

export QODERCN_PERSONAL_ACCESS_TOKEN="your_token"

qodercn -p "Review this change and list potential issues" \
  --output-format json \
  --permission-mode accept_edits \
  --max-turns 20

For authentication, see Sign-in and Authentication. Setting the output format to json makes it easy for later pipeline steps to parse Qoder's result.

​Overview

​Basic usage

​Output formats

​Common flags