> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Running Qoder CLI in Scripts

<div id="overview">
  # Overview
</div>

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`):

```shell theme={null}
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](/en/cli/06-configuration-and-security/permissions) for details.

<div id="basic-usage">
  # Basic Usage
</div>

Pass the prompt as an argument and add `-p`:

```shell theme={null}
qodercli -p "Generate a commit message for this change"
```

You can also pass the prompt via standard input:

```shell theme={null}
echo "Summarize all code changes from yesterday" | qodercli -p
```

Capture the output in a script:

```shell theme={null}
result=$(qodercli -p "List all exported functions in the src directory")
echo "$result"
```

<div id="output-format">
  # Output Format
</div>

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:

```shell theme={null}
# 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.

<div id="common-flags">
  # Common Flags
</div>

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.

<div id="permissions">
  # Permission Control
</div>

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

```shell theme={null}
# 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](/en/cli/06-configuration-and-security/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](/en/cli/06-configuration-and-security/permissions).

<div id="ci-example">
  # CI/CD Example
</div>

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

```shell theme={null}
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](/en/cli/01-getting-started/auth) for authentication methods. Set the output format to `json` to make it easier for subsequent pipeline steps to parse Qoder's results.