docs/cli/headless-mode.mdx

Rama main · réplica de lectura del repositorio original.

---
title: "Headless Mode"
---

Run `cn -p "your prompt"` to execute a single task without an interactive session. The agent runs to completion and prints its response to stdout.

```bash
cn -p "Generate a conventional commit message for the staged changes"
```

## Piping

Pipe data into `cn` to include it as context:

```bash
git diff --staged | cn -p "Write a commit message for this diff"
cat error.log | cn -p "Explain what went wrong"
curl -s https://api.example.com/health | cn -p "Is this healthy?"
```

Pipe the output into other tools:

```bash
cn -p "Generate a commit message" | git commit -F -
cn -p "List all TODO comments in src/" --silent > todos.txt
```

## Output options

| Flag | Effect |
|------|--------|
| `--silent` | Strip `<think>` tags and excess whitespace from output |
| `--format json` | Output structured JSON |

`--silent` is useful when piping output into another program. `--format json` is useful for parsing results programmatically.

## Tool permissions

In headless mode, tools that would normally prompt for approval (`ask` permission) are automatically excluded — there's no one to approve them. To enable write operations, explicitly allow them:

```bash
# Allow the agent to write files
cn -p "Fix the type errors in src/" --allow Write --allow Edit

# Allow everything
cn -p "Set up the project" --allow "*"
```

See [tool permissions](/cli/tool-permissions) for the full policy system.

## Resume in headless mode

Resume a previous session without interactive input:

```bash
cn -p --resume
```

This replays the previous session's history, which can be useful for inspecting past results in automation.

## Examples

```bash
# Git hooks
cn -p "Review staged changes for obvious bugs" --silent

# CI pipeline — allow file writes for auto-fix
cn -p "Fix all ESLint errors in src/" --allow Write --allow Edit --allow Bash

# Generate docs from code
cn -p "@src/api/ Generate OpenAPI documentation for these endpoints" --silent > api-docs.yaml

# Use a specific assistant
cn -p "Triage this error log" --config my-org/error-triage-assistant
```