CLI reference
Complete reference for the CSC command-line interface, including commands and flags.
CLI commands
You can start sessions, pipe content, resume conversations, and manage updates with these commands:
| Command | Description | Example |
|---|---|---|
csc | Start interactive session | csc |
csc "query" | Start interactive session with initial prompt | csc "explain this project" |
csc -p "query" | Query via SDK, then exit | csc -p "explain this function" |
cat file | csc -p "query" | Process piped content | cat logs.txt | csc -p "explain" |
csc -c | Continue most recent conversation in current directory | csc -c |
csc -c -p "query" | Continue via SDK | csc -c -p "Check for type errors" |
csc -r "<session>" "query" | Resume session by ID or name | csc -r "auth-refactor" "Finish this PR" |
csc update | Update to latest version | csc update |
csc auth login | Sign in to your Anthropic account. Use --email to pre-fill your email address, --sso to force SSO authentication, and --console to sign in with Anthropic Console for API usage billing instead of a Claude subscription | csc auth login --console |
csc auth logout | Log out from your Anthropic account | csc auth logout |
csc auth status | Show authentication status as JSON. Use --text for human-readable output. Exits with code 0 if logged in, 1 if not | csc auth status |
csc agents | List all configured subagents, grouped by source | csc agents |
csc auto-mode defaults | Print the built-in auto mode classifier rules as JSON. Use csc auto-mode config to see your effective config with settings applied | csc auto-mode defaults > rules.json |
csc mcp | Configure Model Context Protocol (MCP) servers | See the CSC MCP documentation. |
csc plugin | Manage CSC plugins. Alias: csc plugins. See plugin reference for subcommands | csc plugin install code-review@claude-plugins-official |
csc remote-control | Start a Remote Control server to control CSC from claude.ai or the Claude app. Runs in server mode (no local interactive session). See Server mode flags | csc remote-control --name "My Project" |
csc setup-token | Generate a long-lived OAuth token for CI and scripts. Prints the token to the terminal without saving it. Requires a Claude subscription. See Generate a long-lived token | csc setup-token |
CLI flags
Customize CSC's behavior with these command-line flags. csc --help does not list every flag, so a flag's absence from --help does not mean it is unavailable.
| Flag | Description | Example |
|---|---|---|
--add-dir | Add additional working directories for CSC to read and edit files. Grants file access; most .costrict/ configuration is not discovered from these directories. Validates each path exists as a directory | csc --add-dir ../apps ../lib |
--agent | Specify an agent for the current session (overrides the agent setting) | csc --agent my-custom-agent |
--agents | Define custom subagents dynamically via JSON. Uses the same field names as subagent frontmatter, plus a prompt field for the agent's instructions | csc --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}' |
--allow-dangerously-skip-permissions | Add bypassPermissions to the Shift+Tab mode cycle without starting in it. Lets you begin in a different mode like plan and switch to bypassPermissions later. See permission modes | csc --permission-mode plan --allow-dangerously-skip-permissions |
--allowedTools | Tools that execute without prompting for permission. See permission rule syntax for pattern matching. To restrict which tools are available, use --tools instead | "Bash(git log *)" "Bash(git diff *)" "Read" |
--append-system-prompt | Append custom text to the end of the default system prompt | csc --append-system-prompt "Always use TypeScript" |
--append-system-prompt-file | Load additional system prompt text from a file and append to the default prompt | csc --append-system-prompt-file ./extra-rules.txt |
--bare | Minimal mode: skip auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and AGENTS.md so scripted calls start faster. CSC has access to Bash, file read, and file edit tools. Sets CLAUDE_CODE_SIMPLE. See bare mode | csc --bare -p "query" |
--betas | Beta headers to include in API requests (API key users only) | csc --betas interleaved-thinking |
--channels | (Research preview) MCP servers whose channel notifications CSC should listen for in this session. Space-separated list of plugin:<name>@<marketplace> entries. Requires claude.ai authentication | csc --channels plugin:my-notifier@my-marketplace |
--chrome | Enable Chrome browser integration for web automation and testing | csc --chrome |
--continue, -c | Load the most recent conversation in the current directory | csc --continue |
--dangerously-load-development-channels | Enable channels that are not on the approved allowlist, for local development. Accepts plugin:<name>@<marketplace> and server:<name> entries. Prompts for confirmation | csc --dangerously-load-development-channels server:webhook |
--dangerously-skip-permissions | Skip permission prompts. Equivalent to --permission-mode bypassPermissions. See permission modes for what this does and does not skip | csc --dangerously-skip-permissions |
--debug | Enable debug mode with optional category filtering (for example, "api,hooks" or "!statsig,!file") | csc --debug "api,mcp" |
--debug-file <path> | Write debug logs to a specific file path. Implicitly enables debug mode. Takes precedence over CLAUDE_CODE_DEBUG_LOGS_DIR | csc --debug-file /tmp/claude-debug.log |
--disable-slash-commands | Disable all skills and commands for this session | csc --disable-slash-commands |
--disallowedTools | Tools that are removed from the model's context and cannot be used | "Bash(git log *)" "Bash(git diff *)" "Edit" |
--effort | Set the effort level for the current session. Options: low, medium, high, max (Opus 4.6 only). Session-scoped and does not persist to settings | csc --effort high |
--exclude-dynamic-system-prompt-sections | Move per-machine sections from the system prompt (working directory, environment info, memory paths, git status) into the first user message. Improves prompt-cache reuse across different users and machines running the same task. Only applies with the default system prompt; ignored when --system-prompt or --system-prompt-file is set. Use with -p for scripted, multi-user workloads | csc -p --exclude-dynamic-system-prompt-sections "query" |
--fallback-model | Enable automatic fallback to specified model when default model is overloaded (print mode only) | csc -p --fallback-model sonnet "query" |
--fork-session | When resuming, create a new session ID instead of reusing the original (use with --resume or --continue) | csc --resume abc123 --fork-session |
--from-pr | Resume sessions linked to a specific GitHub PR. Accepts a PR number or URL. Sessions are automatically linked when created via gh pr create | csc --from-pr 123 |
--ide | Automatically connect to IDE on startup if exactly one valid IDE is available | csc --ide |
--init | Run initialization hooks and start interactive mode | csc --init |
--init-only | Run initialization hooks and exit (no interactive session) | csc --init-only |
--include-hook-events | Include all hook lifecycle events in the output stream. Requires --output-format stream-json | csc -p --output-format stream-json --include-hook-events "query" |
--include-partial-messages | Include partial streaming events in output. Requires --print and --output-format stream-json | csc -p --output-format stream-json --include-partial-messages "query" |
--input-format | Specify input format for print mode (options: text, stream-json) | csc -p --output-format json --input-format stream-json |
--json-schema | Get validated JSON output matching a JSON Schema after agent completes its workflow (print mode only, see structured outputs) | csc -p --json-schema '{"type":"object","properties":{...}}' "query" |
--maintenance | Run maintenance hooks and start interactive mode | csc --maintenance |
--max-budget-usd | Maximum dollar amount to spend on API calls before stopping (print mode only) | csc -p --max-budget-usd 5.00 "query" |
--max-turns | Limit the number of agentic turns (print mode only). Exits with an error when the limit is reached. No limit by default | csc -p --max-turns 3 "query" |
--mcp-config | Load MCP servers from JSON files or strings (space-separated) | csc --mcp-config ./mcp.json |
--model | Sets the model for the current session with an alias for the latest model (sonnet or opus) or a model's full name | csc --model claude-sonnet-4-6 |
--name, -n | Set a display name for the session, shown in /resume and the terminal title. You can resume a named session with csc --resume <name>. /rename changes the name mid-session and also shows it on the prompt bar | csc -n "my-feature-work" |
--no-chrome | Disable Chrome browser integration for this session | csc --no-chrome |
--no-session-persistence | Disable session persistence so sessions are not saved to disk and cannot be resumed (print mode only) | csc -p --no-session-persistence "query" |
--output-format | Specify output format for print mode (options: text, json, stream-json) | csc -p "query" --output-format json |
--enable-auto-mode | Unlock auto mode in the Shift+Tab cycle. Requires a Team, Enterprise, or API plan and Claude Sonnet 4.6 or Opus 4.6 | csc --enable-auto-mode |
--permission-mode | Begin in a specified permission mode. Accepts default, acceptEdits, plan, auto, dontAsk, or bypassPermissions. Overrides defaultMode from settings files | csc --permission-mode plan |
--permission-prompt-tool | Specify an MCP tool to handle permission prompts in non-interactive mode | csc -p --permission-prompt-tool mcp_auth_tool "query" |
--plugin-dir | Load plugins from a directory for this session only. Each flag takes one path. Repeat the flag for multiple directories: --plugin-dir A --plugin-dir B | csc --plugin-dir ./my-plugins |
--print, -p | Print response without interactive mode (see Agent SDK documentation for programmatic usage details) | csc -p "query" |
--remote | Create a new web session on claude.ai with the provided task description | csc --remote "Fix the login bug" |
--remote-control, --rc | Start an interactive session with Remote Control enabled so you can also control it from claude.ai or the Claude app. Optionally pass a name for the session | csc --remote-control "My Project" |
--remote-control-session-name-prefix <prefix> | Prefix for auto-generated Remote Control session names when no explicit name is set. Defaults to your machine's hostname, producing names like myhost-graceful-unicorn. Set CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX for the same effect | csc remote-control --remote-control-session-name-prefix dev-box |
--replay-user-messages | Re-emit user messages from stdin back on stdout for acknowledgment. Requires --input-format stream-json and --output-format stream-json | csc -p --input-format stream-json --output-format stream-json --replay-user-messages |
--resume, -r | Resume a specific session by ID or name, or show an interactive picker to choose a session | csc --resume auth-refactor |
--session-id | Use a specific session ID for the conversation (must be a valid UUID) | csc --session-id "550e8400-e29b-41d4-a716-446655440000" |
--setting-sources | Comma-separated list of setting sources to load (user, project, local) | csc --setting-sources user,project |
--settings | Path to a settings JSON file or a JSON string to load additional settings from | csc --settings ./settings.json |
--strict-mcp-config | Only use MCP servers from --mcp-config, ignoring all other MCP configurations | csc --strict-mcp-config --mcp-config ./mcp.json |
--system-prompt | Replace the entire system prompt with custom text | csc --system-prompt "You are a Python expert" |
--system-prompt-file | Load system prompt from a file, replacing the default prompt | csc --system-prompt-file ./custom-prompt.txt |
--teleport | Resume a web session in your local terminal | csc --teleport |
--teammate-mode | Set how agent team teammates display: auto (default), in-process, or tmux. See Choose a display mode | csc --teammate-mode in-process |
--tmux | Create a tmux session for the worktree. Requires --worktree. Uses iTerm2 native panes when available; pass --tmux=classic for traditional tmux | csc -w feature-auth --tmux |
--tools | Restrict which built-in tools CSC can use. Use "" to disable all, "default" for all, or tool names like "Bash,Edit,Read" | csc --tools "Bash,Edit,Read" |
--verbose | Enable verbose logging, shows full turn-by-turn output | csc --verbose |
--version, -v | Output the version number | csc -v |
--worktree, -w | Start CSC in an isolated git worktree at <repo>/.costrict/worktrees/<name>. If no name is given, one is auto-generated | csc -w feature-auth |
System prompt flags
CSC provides four flags for customizing the system prompt. All four work in both interactive and non-interactive modes.
| Flag | Behavior | Example |
|---|---|---|
--system-prompt | Replaces the entire default prompt | csc --system-prompt "You are a Python expert" |
--system-prompt-file | Replaces with file contents | csc --system-prompt-file ./prompts/review.txt |
--append-system-prompt | Appends to the default prompt | csc --append-system-prompt "Always use TypeScript" |
--append-system-prompt-file | Appends file contents to the default prompt | csc --append-system-prompt-file ./style-rules.txt |
--system-prompt and --system-prompt-file are mutually exclusive. The append flags can be combined with either replacement flag.
For most use cases, use an append flag. Appending preserves CSC's built-in capabilities while adding your requirements. Use a replacement flag only when you need complete control over the system prompt.