CLI Flags Reference

Complete reference for all global flags and command-specific flags. Global flags can be used with any command. Flags are set on the command line and take precedence over environment variables and configuration files.

✓Tip
Flags can also be set in codecli.json under the flags key. Command-line flags always override config file values.

Global Flags

Available on every command.

FlagShortTypeDefaultDescription
--help-hbooleanfalseShow help for the current command and exit
--version-vbooleanfalsePrint the codecli version and exit
--print-logsbooleanfalsePrint internal logs to stderr during execution
--log-level-lstringwarnLog level: trace, debug, info, warn, error, off

Model Flags

Control which AI model is used and how it generates responses.

FlagShortTypeDefaultDescription
--model-mstringautoAI model to use. Supports provider/model syntax: "anthropic/claude-sonnet-4-20250514", "openai/gpt-4o", or shorthand: "sonnet", "opus", "gpt-4o"
--agent-astring---Named agent configuration to load (from codecli.json agents section)
--variantstring---Model variant preset: fast (Haiku/GPT-4o-mini), smart (Sonnet/GPT-4o), reasoning (Opus/o1)
--thinkingbooleanfalseEnable extended thinking / chain-of-thought mode for supported models

Session Flags

Control session selection and continuation.

FlagShortTypeDefaultDescription
--continue-cbooleanfalseResume the most recent session
--session-sstring---Resume a specific session by its UUID
--resumebooleanfalseAlias for --continue
--title-tstring---Set a human-readable title for the new session

Output Flags

Control the format and delivery of output.

FlagShortTypeDefaultDescription
--raw-rbooleanfalseOutput raw text without any formatting or color codes
--stream / --no-streambooleanvariesEnable or disable streaming response tokens. Default is true for chat/tui, false for run.
--format-fstringtextOutput format: text, json, markdown

Permission Flags

Control tool execution permissions.

FlagShortTypeDefaultDescription
--dangerously-skip-permissionsbooleanfalseSkip all permission prompts. Tools execute without confirmation. Requires CODECLI_DANGEROUSLY_SKIP_PERMISSIONS or explicit consent.
--allow-dangerously-skip-permissionsbooleanfalseAllow the --dangerously-skip-permissions flag to be used. Must be set in the global config, not on the command line.
✖Danger
The --dangerously-skip-permissions flag should only be used in trusted automated environments such as CI/CD pipelines. Never use it interactively on a developer workstation.

Context Flags

Control the working context, including directories, system prompts, and project configuration.

FlagShortTypeDefaultDescription
--add-dirstring---Add a directory to the workspace. Can be repeated to add multiple directories.
--append-system-promptstring---Append text to the end of the system prompt
--barebooleanfalseSkip loading project config, CLAUDE.md files, and default plugins

Server Flags

Control network server behavior (for serve, mcp-server, and acp commands).

FlagShortTypeDefaultDescription
--remotebooleanfalseConnect to a remote codecli server instead of running locally
--port-pnumbervariesPort number. Default: 8090 (serve), 4097 (mcp-server), 4517 (acp)
--hostname-HstringlocalhostHostname to bind the server to. Use 0.0.0.0 for all interfaces.
--mdnsbooleanfalseAdvertise the server via mDNS/Bonjour for local network discovery

Other Flags

FlagShortTypeDefaultDescription
--enable-auto-modebooleanfalseEnable automatic tool execution. The agent will execute tools without asking for confirmation.
--mainframebooleanfalseLaunch in mainframe mode with multiple agent panes in a split terminal layout
--backgroundbooleanfalseRun codecli as a background daemon process. Attach later with codecli attach.
--compact-thresholdnumberautoToken count threshold at which auto-compaction triggers. Set to 0 to disable.
--presetstring---Load a named preset from the config file. Presets bundle model, flags, and system prompt overrides.
PreviousEnvironment VariablesNextMCP Server