Guide
Headless mode in every AI coding agent: claude -p, codex exec, gemini -p, Cursor agent -p and copilot -p for scripts and CI (2026)
How do I run Claude Code, Codex, Gemini CLI, Cursor CLI or GitHub Copilot CLI non-interactively in a script or CI job?
Every major coding agent CLI has a one-shot mode: claude -p for Claude Code, codex exec for Codex, gemini -p for Gemini CLI, agent -p for the Cursor CLI and copilot -p for GitHub Copilot CLI. Claude Code, Gemini CLI and Cursor can print JSON with --output-format json. Each one needs its own flag before it will edit files or run commands without asking: --allowedTools or --permission-mode (Claude Code), --sandbox workspace-write (Codex), --force (Cursor) and --allow-tool (Copilot).
Coding agent settings change often
Get one email a week when a setting, flag or permission rule changes, checked against the vendor docs.
Quick answer: the one-shot command
- Claude Code: claude -p "prompt" (or --print). Exits 0 on success and non-zero when the run fails.
- Codex: codex exec "prompt". OpenAI's docs say to use codex exec --sandbox workspace-write for non-interactive runs that edit files.
- Gemini CLI: gemini -p "prompt" (or --prompt). Headless mode also starts whenever the CLI runs in a non-TTY environment, for example with piped input.
- Cursor CLI: agent -p "prompt" (or --print). It has access to all tools, including write and shell.
- GitHub Copilot CLI: copilot -p "prompt" (or --prompt). You can also pipe a prompt into copilot, but piped input is ignored if you also pass -p.
Machine-readable output
- Claude Code: --output-format text (default), json or stream-json. JSON holds the text in result, plus the session ID and total_cost_usd. Add --json-schema to get a structured_output field that matches your schema.
- Gemini CLI: --output-format json returns one object with response, stats and an optional error. The streaming format emits JSONL events: init, message, tool_use, tool_result, error and result.
- Cursor CLI: --output-format text (default), json or stream-json. It only works with --print. --stream-partial-output adds text deltas with stream-json.
- GitHub Copilot CLI: add -s (silent) to drop session metadata so you capture clean text.
Extract the answer with jq
claude -p "Summarize this project" --output-format json | jq -r '.result' gemini -p "Summarize this project" --output-format json | jq -r '.response' result=$(copilot -p 'What version of Node.js does this project require? Give the number only.' -s)
Let it edit files and run commands
- Claude Code: list tools with --allowedTools "Bash,Read,Edit" (rule syntax such as Bash(git diff *) works), or set --permission-mode acceptEdits, auto or dontAsk. dontAsk denies anything that would prompt, which suits locked-down CI.
- Codex: --sandbox read-only, workspace-write or danger-full-access. For a read-only CI job OpenAI lists --sandbox read-only --ask-for-approval never.
- Cursor CLI: -f or --force (alias --yolo) allows commands unless they are explicitly denied. --trust trusts the workspace without prompting in headless mode.
- GitHub Copilot CLI: grant only what the job needs with --allow-tool, for example --allow-tool='shell(git:*)'. GitHub advises against --allow-all outside a sandbox.
Same task, four agents
claude -p "Fix the lint errors" --permission-mode acceptEdits codex exec --sandbox workspace-write "Fix the lint errors" agent -p --force "Fix the lint errors" copilot -p 'Fix all ESLint errors in this project' --allow-tool='write, shell(npm:*), shell(npx:*)'
Exit codes and authentication in CI
- Claude Code: exit 0 on success, non-zero on failure, 143 when stopped with SIGTERM. In CI add --bare, which skips local hooks, skills, plugins, MCP servers, auto memory and CLAUDE.md, and set ANTHROPIC_API_KEY because bare mode never reads OAuth credentials or the keychain.
- Gemini CLI: 0 success, 1 general error or API failure, 42 input error, 53 turn limit exceeded.
- Cursor CLI: set CURSOR_API_KEY (or pass --api-key).
- GitHub Copilot CLI: GitHub's Actions example sets COPILOT_GITHUB_TOKEN from a personal access token secret.
Note: the Gemini CLI docs say Antigravity CLI replaced Gemini CLI on June 18, 2026 for unpaid tier and Google One users.
Continue a run
- Claude Code: --continue picks up the most recent conversation, --resume <session_id> a specific one.
- Cursor CLI: --resume [chatId] resumes a chat, and --continue resumes the previous one.
Full headless guide for each agent
- Claude Code headless mode: claude -p, JSON output and --bare
- codex exec: run Codex in scripts and CI
- Gemini CLI headless mode: gemini -p and exit codes
- Cursor CLI: install, print mode, permissions and CI
- GitHub Copilot CLI permissions: --allow-tool and --deny-tool
- Compare: allow all commands in every AI coding agent
- Compare: hooks in every AI coding agent
Get coding agent settings changes by email
When a setting, flag or permission rule in this guide changes, it goes in the weekly AgentAtlas update, checked against the vendor docs. One email a week.
Sources
Other guides
Reviewed Oct 18, 2026. Settings change often; the linked vendor docs are the source of truth.