Flags

All command-line flags can be used with cos start or other commands. Flags override configuration file settings.

Global flags

Quick Reference

Flag	Short	Description	Default
`--api-key`	`-k`	API token override	From config
`--auto-accept`	-	Auto-approve all tools	`false`
`--auto-accept-plans`	-	Auto-approve plan mode	`false`
`--browser-agent-model`	-	Model for browser subagents	`gemini-3-flash-preview`
`--cdp-url`	-	Chrome CDP URL	From config
`--enable-agent-browser`	-	Enable browser control	Saved / `false`
`--enable-agent-desktop`	-	Enable desktop control	Saved / `false`
`--enable-agent-commits`	-	Enable Agent Commits	`true`
`--cwd`	-	Working directory	`.`
`--debug`	-	Debug mode	`false`
`--direct`	-	Connect to remote-runtime	-
`--forceUpdate`	-	Force update on boot	`false`
`--host`	-	API host/base URL	From config
`--inference`	`-i`	Inference base URL	From config
`--lsp-diagnostics-on-file-read`	-	LSP diagnostics on read	`false`
`--lsp-diagnostics-on-file-write`	-	LSP diagnostics on write	`false`
`--mcp-config`	-	MCP config JSON path	-
`--mode`	-	Startup mode	Last used / `normal`
`--am`	-	Start in Auto mode	`false`
`--mm`	-	Start in Manual mode	`false`
`--pm`	-	Start in Plan mode	`false`
`--sm`	-	Start in Swarm mode	`false`
`--model`	-	Model override	From config
`--parallel-tool-calls`	-	Allow parallel tools	`true`
`--profile`	-	Config profile	-
`--prompt`	`-p`	One-shot prompt	-
`--prompt-file`	-	Read the prompt from a file	-
`--reasoning`	-	Reasoning level	From config
`--response-format`	-	Structured output schema	-
`--system-prompt`	`-s`	System prompt ID	`lumen`
`--system-prompt-file`	-	Custom prompt file	-
`--title-model`	-	Model for titles	From config
`--tool-call-limit`	-	Per-tool budgets	-
`--workspace`	-	Workspace mode	`os`
`--worktree-name`	-	Worktree name	-
`--wsresponses`	-	WebSocket mode	`false`

`--api-key` / `-k`

API token override for a single session.

# Override API key
cos start --api-key sk-abc123

# With one-shot mode for automation
cos start -k $OPENAI_API_KEY --prompt "Review code" --auto-accept

`--auto-accept`

⚠️ Use with caution — Puts the agent in fully autonomous mode without confirmations.

# Autonomous refactoring
cos start --auto-accept --prompt "Refactor auth to JWT"

# With Agent Commits enabled for tracking
cos start --auto-accept --enable-agent-commits=true

# CI/CD automation
cos start --auto-accept --prompt "Run tests and fix failures" --cwd /path/to/project

`--auto-accept-plans`

Auto-approve plan mode transitions but review individual edits.

# Auto-approve plans only
cos start --auto-accept-plans

# With high reasoning for better planning
cos start --auto-accept-plans --reasoning high --prompt "Design database schema"

`--browser-agent-model`

Model for browser automation subagents.

# Faster model for simple tasks
cos start --cdp-url http://localhost:9222 --browser-agent-model lumen-scout

# More capable model for complex automation
cos start --cdp-url http://localhost:9222 --browser-agent-model claude-sonnet-4-6-1m

`--enable-agent-browser`

Enable browser-control tools and save the preference in your user config. Browser control is disabled until you enable it with this flag or from the Command Centre Settings tab.

cos start --enable-agent-browser

Pass --enable-agent-browser=false or use the Command Centre Settings tab to disable browser control. The Settings tab also controls whether a locally launched browser runs automatically, headlessly, or headfully.

`--enable-agent-desktop`

Enable foreground desktop-control tools and save the preference in your user config. Desktop control is disabled until you enable it and requires a graphical desktop.

cos start --enable-agent-desktop

# Disable it again and save the change
cos start --enable-agent-desktop=false

--enable-agent-computer remains available as a compatibility alias.

`--cdp-url`

Chrome DevTools Protocol URL for browser automation.

# Local Chrome with remote debugging
cos start --enable-agent-browser --cdp-url http://localhost:9222

# Remote Chrome instance
cos start --enable-agent-browser --cdp-url http://192.168.1.100:9222

# One-shot screenshot
cos start --enable-agent-browser --cdp-url http://localhost:9222 --prompt "Screenshot example.com" --auto-accept

Start Chrome with remote debugging:

# macOS
open -n -a "Google Chrome" --args --remote-debugging-port=9222 --user-data-dir=/tmp/cosine-chrome

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/cosine-chrome

`--enable-agent-commits`

Enable or disable automatic Agent Commits after each editing turn so agent changes are recorded as reviewable, reversible Git history.

Aliases:

--enable-agent-commit
--enable-commit
--enable-commits
--commit

# Disable Agent Commits for this session
cos start --enable-agent-commits=false --prompt "Experimental changes"

# Explicitly enable (default)
cos start --enable-agent-commits=true

# Short alias
cos start --commit=false

`--cwd`

Set working directory for the session.

# Work on specific project
cos start --cwd ~/projects/my-app

# With automation
cos start --cwd ~/projects/api --prompt "Generate docs" --auto-accept

# Batch script example
#!/bin/bash
for project in ~/projects/*/; do
    cos start --cwd "$project" --prompt "Update deps" --auto-accept
done

`--debug`

Debug mode dumps context window to /tmp/cosine/window.json.

# Enable debug logging
cos start --debug

# Debug with output to file
cos start --debug --prompt "Debug this" 2>&1 | tee debug.log

`--direct`

Connect to remote runtime TCP address.

# Local remote-runtime
cos start --direct localhost:9876

# Remote instance
cos start --direct 192.168.1.50:9876 --api-key sk-...

# Containerized environment
cos start --direct cos-runtime.internal:9876 --prompt "Heavy computation"

`--forceUpdate`

Force update check on startup (for testing).

# Force immediate update
cos start --forceUpdate

`--host`

API host/base URL override.

# Custom Cosine instance
cos start --host https://cosine.mycompany.internal

# Development/testing
cos start --host http://localhost:8080 --debug

`--inference` / `-i`

OpenAI-compatible inference endpoint.

# Use OpenAI directly
cos start --inference https://api.openai.com/v1 --api-key $OPENAI_API_KEY

# Local LLM server
cos start -i http://localhost:8000/v1

# Azure OpenAI
cos start -i https://my-resource.openai.azure.com/openai/deployments/my-deployment

`--lsp-diagnostics-on-file-read`

Include LSP diagnostics in read_file output.

# Enable diagnostics on read
cos start --lsp-diagnostics-on-file-read

# Fix all TypeScript errors
cos start --lsp-diagnostics-on-file-read --prompt "Fix all TS errors"

`--lsp-diagnostics-on-file-write`

Refresh LSP diagnostics after file writes.

# Enable on write
cos start --lsp-diagnostics-on-file-write

# Both read and write
cos start --lsp-diagnostics-on-file-read --lsp-diagnostics-on-file-write

`--mcp-config`

Path to MCP server configuration JSON.

# Project-specific MCP config
cos start --mcp-config ./project-mcp.json

# Environment-specific config
cos start --mcp-config ~/.cosine/mcp-staging.json

# Disable MCP temporarily
cos start --mcp-config /dev/null

`--mode`

Set the startup mode. The selected mode is persisted across sessions — if you don’t pass --mode on the next launch, Cosine restores the last mode you used.

# Start in plan mode
cos start --mode plan

# Start in auto mode
cos start --mode auto

# Start in swarm mode
cos start --mode swarm

# Start in manual mode (default)
cos start --mode manual

Accepted values: normal (same as manual), auto, plan, swarm

`--am`

Shorthand for --mode auto. Start in Auto mode.

cos start --am

`--mm`

Shorthand for --mode manual. Start in Manual mode.

cos start --mm

`--pm`

Shorthand for --mode plan. Start in Plan mode.

cos start --pm

`--sm`

Shorthand for --mode swarm. Start in Swarm mode.

cos start --sm

`--model`

Override the inference model.

# Use specific model
cos start --model gpt-5.5

# Fast model for simple tasks
cos start --model lumen-scout --prompt "Generate test data"

# Complex tasks with reasoning
cos start --model claude-opus-4-8 --reasoning high --prompt "Design distributed system"

# One-shot PR review
cos start --model gpt-5.3-codex --prompt "Review this PR"

`--parallel-tool-calls`

Allow/disable parallel tool execution.

# Force sequential for debugging
cos start --parallel-tool-calls=false

# Enable parallel (default)
cos start --parallel-tool-calls=true

# Debug race conditions
cos start --parallel-tool-calls=false --prompt "Debug file modification issues"

`--profile`

Use configuration profile.

# Work profile
cos start --profile work

# Personal profile
cos start --profile personal

# Profile with debug
cos start --profile staging --debug

`--prompt` / `-p`

One-shot mode for automation.

# Quick question
cos start --prompt "What does this function do?"

# Batch review script
#!/bin/bash
for file in $(git diff --name-only HEAD~1); do
    cos start -p "Review $file for security" --cwd . --auto-accept
done

# CI/CD integration
cos start -p "Run lint and fix issues" --auto-accept --enable-agent-commits=false

`--prompt-file`

Read the prompt text from a file instead of passing it inline on the command line.

# Start a task from a markdown brief
cos start --prompt-file ./task.md

# Use a saved review prompt
cos start --prompt-file ./prompts/review.txt --auto-accept-plans

--prompt-file is mutually exclusive with --prompt.

`--reasoning`

Set reasoning effort: none, low, medium, high, xhigh, adaptive, or max.

# Fast responses
cos start --reasoning low --prompt "List TODO comments"

# Balanced (default)
cos start --reasoning medium

# Deep analysis
cos start --reasoning high --prompt "Refactor monolith to microservices"

# Maximum depth (GPT/Codex only)
cos start --reasoning xhigh --model gpt-5.5 --prompt "Prove algorithm correctness"

# Let supported Claude 4.6 models choose how much thinking they need
cos start --reasoning adaptive --model claude-sonnet-4-6-1m --prompt "Investigate a performance regression"

For help choosing a level, see Reasoning.

Startup flags such as --mode and --reasoning are also persisted across sessions, so your preferred launch configuration carries forward unless you override it again.

`--response-format`

Structured JSON output schema (headless mode).

# Extract structured data
cos start --prompt "Extract user info" \
  --response-format '{"name":"user_info","strict":true,"schema":{"type":"object","properties":{"name":{"type":"string"},"age":{"type":"integer"}}}}'

# Parse logs to JSON
cos start --prompt "Parse logs" \
  --response-format '{"name":"errors","schema":{"type":"array","items":{"type":"object","properties":{"ts":{"type":"string"},"msg":{"type":"string"}}}}}'

# Pipe to jq
cos start --prompt "Analyze deps" --response-format '...' | jq '.dependencies'

`--system-prompt` / `-s`

System prompt ID: lumen, lumenLegacy, judge, orchestrator.

# Code review
cos start --system-prompt judge --prompt "Review this PR"

# Complex orchestration
cos start --system-prompt orchestrator --prompt "Set up microservice"

# General coding (default)
cos start --system-prompt lumen

`--system-prompt-file`

Path to custom system prompt file.

# Custom prompt from file
cos start --system-prompt-file ./prompts/security-expert.txt

# Project AGENTS.md
cos start --system-prompt-file ./AGENTS.md

# With model selection
cos start --system-prompt-file ./custom-prompt.txt --model gpt-5.5

`--title-model`

Model for generating session titles.

# Cheap model for titles
cos start --model gpt-5.5 --title-model lumen-scout

# Default (uses main model)
cos start --model gpt-5.3-codex

`--tool-call-limit`

Budget tool usage with tool=N pairs.

# Limit expensive operations
cos start --tool-call-limit "web_search=5,web_fetch=10"

# Prevent excessive edits
cos start --tool-call-limit "edit=20,terminal=5,web_search=3"

# CI safety: no terminal
cos start --tool-call-limit "terminal=0" --prompt "Review only"

`--workspace`

Workspace mode: os, vfs, worktree.

# Direct filesystem (default)
cos start --workspace os

# Isolated virtual filesystem
cos start --workspace vfs --prompt "Experiment safely"

# Git worktree
cos start --workspace worktree --worktree-name feature-x

# Named worktree branch
cos start --workspace worktree --worktree-name bugfix-123

`--worktree-name`

Name for git worktree (with --workspace worktree).

# Named feature worktree
cos start --workspace worktree --worktree-name new-auth-system

# Parallel experiments
cos start --workspace worktree --worktree-name experiment-1 --prompt "Try approach A"
cos start --workspace worktree --worktree-name experiment-2 --prompt "Try approach B"

# Clean up
git worktree remove experiment-1
git worktree remove experiment-2

`--wsresponses`

WebSocket mode for lower latency.

# Enable WebSocket
cos start --wsresponses

# With performance flags
cos start --wsresponses --reasoning low --model lumen-scout

# Interactive sessions
cos start --wsresponses --prompt "Quick design session"

Commands — Command overview
Overview — Product overview and where to start
Quickstart — Fastest path to first success
Configuration — Config files and precedence
MCP Configuration — Connect external tools

Flags

Global flags

Quick Reference

--api-key / -k

--auto-accept

--auto-accept-plans

--browser-agent-model

--enable-agent-browser

--enable-agent-desktop

--cdp-url

--enable-agent-commits

--cwd

--debug

--direct

--forceUpdate

--host

--inference / -i

--lsp-diagnostics-on-file-read

--lsp-diagnostics-on-file-write

--mcp-config

--mode

--am

--mm

--pm

--sm

--model

--parallel-tool-calls

--profile

--prompt / -p

--prompt-file

--reasoning

--response-format

--system-prompt / -s

--system-prompt-file

--title-model

--tool-call-limit

--workspace

--worktree-name

--wsresponses

Related reference