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

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

How to allow Cursor to run all commands: Run Everything, allowlist and sandboxHow to allow Claude Code to run all commands: permission modes, allow rules and skip permissionsClaude Code permissions: allow, ask and deny rules, rule syntax and allowed toolsCodex CLI: approval and sandbox modesGemini CLI: YOLO mode, auto_edit and allowing specific shell commandsCursor Privacy Mode: telemetry, training and data retentionClaude Code telemetry and data retention: what is sent and how to turn it offGemini CLI: turn off usage statistics and telemetryCLAUDE.md: where it goes, how it loads, and how it works with AGENTS.mdClaude Code hooks: format on save, block risky edits, get notifiedClaude Code subagents: create one, limit its tools, and call itAdd MCP servers to Cursor with mcp.json: Keep files out of Cursor with .cursorignore: Configure Codex with config.toml: Configure Gemini CLI with settings.json: Add MCP servers to Claude Code (claude mcp add, .mcp.json, scopes): Claude Code custom slash commands and skills (SKILL.md): GitHub Copilot custom instructions: Adding MCP servers to GitHub Copilot: Claude Code settings.json: file locations, precedence, and key settingsClaude Code plugins and marketplaces: install, create, and shareGemini CLI extensions and custom commands: Configuring OpenCode with opencode.json: Cline Rules: workspace, global, and conditional rulesKiro steering files: .kiro/steering, inclusion modes, and AGENTS.mdZed agent: instruction files, MCP servers, tool permissions, and ACP agentsCursor CLI: install, headless mode, permissions and CIAider: CONVENTIONS.md, .aider.conf.yml and API keysJunie guidelines, MCP and the Action Allowlist: Amp AGENTS.md, settings.json and MCP: Configure Goose extensions, hints, recipes and permissions: Customize OpenHands with skills, AGENTS.md, setup.sh and MCP: Configure Factory Droid CLI: AGENTS.md, settings.json, autonomy, custom droids and MCPConfigure Qwen Code: settings.json, providers, QWEN.md, MCP and approval modesCursor hooks: hooks.json, beforeShellExecution, afterFileEdit and exit codesCursor sandbox: sandbox.json, network allowlist and run modesCursor settings: settings.json, Cursor Settings and the ~/.cursor config filesCursor browser agent: @browser, browser automation and approval modesCursor subagents: .cursor/agents, frontmatter, built-in Explore and BrowserCursor telemetry and OpenTelemetry export (Privacy Mode, OTLP, Analytics API): Cursor rules setup: project, user and Team Rules, .mdc frontmatter, globs and AGENTS.mdClaude Code headless mode: claude -p, --output-format json, --bare and CI flagsClaude Code statusline: custom status bar in settings.json with context %, cost and git branchClaude Code /model: switch models, aliasesClaude Code /cost and /usage: check token spend, usage limits and reduce costsClaude Code VS Code extension: install, shortcuts, settings and /ideCodex AGENTS.md: global, project and override instruction files explainedCodex MCP servers: codex mcp add and [mcp_servers] in config.tomlCodex sandbox modes: read-only, workspace-write, danger-full-access and network accesscodex exec: run Codex non-interactively in scripts and CI with JSON outputCodex skills: create SKILL.md, skill folder locations and $skill invocationGEMINI.md in Gemini CLI: context file locations, imports and /memoryGemini CLI MCP servers: gemini mcp add and mcpServers in settings.jsonGemini CLI custom slash commands: TOML files, {{args}}, !{shell} and @{file}Gemini CLI headless mode: gemini -p, JSON output and exit codes for scripts and CIGemini CLI sandbox: enable Docker, Podman, macOS Seatbelt or gVisorcopilot-setup-steps.yml: set up the GitHub Copilot cloudGitHub Copilot CLI permissions: --allow-tool, --deny-tool, --allow-all-tools and trusted directoriesGitHub Copilot custom agents: .github/agents/*.agent.md profiles, tools and frontmatterGitHub Copilot code review settings: automatic PR reviews, rulesets, effort level and approvalsOpenCode MCP Server Setup: Local and Remote Servers in opencode.jsonOpenCode Permissions: Allow, Ask or Deny Bash, Edit and WebfetchOpenCode Custom Agents and Subagents: Markdown Files, Modes and @ MentionsCline MCP Setup: cline_mcp_settings.json for Local and Remote ServersCline Auto Approve and YOLO Mode: Run Commands and Edits Without PromptsCline Skills: SKILL.md Location, Format and Slash Command UseAmp MCP Setup: amp mcp add, amp.mcpServers and Workspace ApprovalAmp AGENTS.md: File Locations, @ Mentions and Glob-Scoped GuidanceAmp Skills: SKILL.md Folders, amp skill add and Search OrderKiro MCP Setup: .kiro/settings/mcp.json, autoApprove and OAuthKiro Hooks: .kiro/hooks JSON, PreToolUse, PostFileSave and StopKiro Permissions: permissions.yaml Allow, Ask and Deny RulesFactory Droid MCP Setup: droid mcp add, mcp.json Locations and /mcpFactory Droid Hooks: hooks.json, PreToolUse Matchers and Exit CodesFactory Droid Custom Droids (Subagents): .factory/droids Markdown FilesJunie MCP Setup: .junie/mcp/mcp.json for CLI and /mcp CommandJunie Brave Mode and Action Allowlist: Auto-Approve Commands in Junie CLIJunie Custom Slash Commands: .junie/commands Markdown Files and Argumentsgoose .goosehints and AGENTS.md: Global and Project Instructionsgoose Permission Modes: GOOSE_MODE auto, approve, smart_approve and chatgoose Recipes: recipe.yaml Format, Parameters and goose run --recipeZed Agent Tool Permissions: Auto-Approve Terminal Commands with tool_permissionsUse Claude, Codex and Gemini CLI in Zed: External Agents and agent_serversZed with Ollama, LM Studio and llama.cpp: Local Model Setup and Context LengthMCP 2026-07-28 Migration Guide: Stateless Protocol, No Sessions, server/discover, MRTR, and SDK v2 UpgradeSubagents and Custom Agents Compared: Claude Code vs Codex vs Cursor vs Gemini CLI vs GitHub CopilotAllow all commands in any AI coding agent: Cursor, Claude Code, Codex, Gemini CLI, Copilot CLI and 7 moreAdd an MCP server to any AI coding agent: Claude Code, Cursor, Codex, Gemini CLI, VS Code and 8 moreSettings file locations for every AI coding agent: Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Qwen Code, Amp and Factory DroidRules and instruction files in every AI coding agent: .cursor/rules, CLAUDE.md, AGENTS.md, GEMINI.md, Copilot instructions and moreGemini CLI hooks: settings.json, BeforeTool, AfterTool, exit codes and /hooksGitHub Copilot hooks: .github/hooks/*.json for Copilot CLI and the cloud agentHooks in every AI coding agent: Claude Code, Cursor, Gemini CLI, GitHub Copilot, Kiro and Factory DroidAgent Skills (SKILL.md) in every AI coding agent: Claude Code, Codex, Cline, Amp and OpenHandsHow to deploy a remote MCP server (Streamable HTTP): Cloudflare Workers, Vercel, Railway and moreClaude Code sandbox: /sandbox, sandbox.enabled, allowedDomains, excludedCommands and strict modeSandbox modes in every AI coding agent: Claude Code, Cursor, Codex and Gemini CLI compared

Reviewed Oct 18, 2026. Settings change often; the linked vendor docs are the source of truth.