CLI Configuration

Cosine CLI can be configured through multiple sources: command-line flags, configuration files, and environment variables. This guide covers all configuration options and how to use them effectively.

Configuration Sources (Priority Order)

Configuration is resolved in this order (highest to lowest priority):

1. Command-line flags - Override everything else
2. Repository config - Project-specific settings in cosine.toml
3. User config - Personal settings in ~/.cosine.toml
4. Environment variables - System-level overrides
5. Default values - Built-in defaults

Configuration Files

User Configuration (~/.cosine.toml)

The main configuration file for your user account. Store personal preferences, API tokens, and global settings here.

[auth]
user_id = "usr_123456789"
token = "your_api_token_here"

[api]
base_url = "https://api.cosine.wtf"

[inference]
base_url = "https://api.cosine.wtf"
model = "lumen"
max_context_tokens = 128000
max_turns = 100

[config]
system_prompt_id = "lumen"
latex_formatting = false
reasoning_level = "medium"

[browser]
cdp_url = "http://localhost:9222"

[telemetry]
enabled = true

Repository Configuration (cosine.toml or .cosine.toml)

Project-specific configuration that lives in your repository. This is ideal for team settings and project-specific behavior.

is_topmost_config = true

[agent]
model = "codex"
extra_context = "AGENTS.md"

[hooks]
on_save = "go test ./..."

Profile-specific Configs

Create multiple configuration profiles for different contexts:

In your repo:

# cosine.work.toml for work projects
cos --profile work start

# cosine.personal.toml for personal projects
cos --profile personal start

In your home directory:

~/.cosine.work.toml

cos --profile work start

# ~/.cosine.personal.toml
cos --profile personal start

Profile resolution order:

1. Check for cosine.<profile>.toml in the repo
2. Check for ~/.cosine.<profile>.toml in home

Configuration Sections

Authentication ([auth])

Your Cosine account credentials.

Field	Type	Description
user_id	string	Your Cosine user ID
token	string	Your API authentication token

Setting credentials:

# Via login command (recommended)
cos login

# Or manually via flag
cos start --api-key your_token_here

API Settings ([api])

Base configuration for Cosine’s API.

Field	Type	Default	Description
base_url	string	https://api.cosine.wtf	Base URL for API requests

Inference Settings ([inference])

Configure the AI model and inference behavior.

Field	Type	Default	Description
base_url	string	https://api.cosine.wtf	OpenAI-compatible inference endpoint
model	string	codex	Default model for sessions
max_context_tokens	int	0 (unlimited)	Maximum context window size
max_turns	int	0 (unlimited)	Maximum conversation turns

Available models:

• codex - Default model for general tasks
• lumen - Alternative model optimized for specific tasks
• judge - Model for evaluation tasks
• orchestrator - Model for orchestration tasks

General Config ([config])

Miscellaneous configuration options.

Field	Type	Default	Description
system_prompt_id	string	lumen	Default system prompt ID
latex_formatting	bool	false	Enable LaTeX formatting in responses
reasoning_level	string	"medium"	Default reasoning effort level
shell	string	""	Preferred shell for terminal sessions
checkpointing	bool	true	Enable automatic checkpointing each turn

Reasoning levels:

• low - Faster responses, less thorough
• medium - Balanced speed and depth
• high - Slower but more thorough
• xhigh - Maximum depth (Codex models only)

Shell configuration:

By default, the CLI uses your system’s `$SHELL` environment variable (falling back to `/bin/bash` on Unix or `cmd.exe` on Windows). You can override this to use a different shell:

[config]
shell = "/opt/homebrew/bin/fish"

Common shell paths:

• Bash: `/bin/bash`
• Zsh: `/bin/zsh` or `/usr/local/bin/zsh`
• Fish: `/opt/homebrew/bin/fish` or `/usr/bin/fish`
• Dash: `/bin/dash`

The configured shell must exist on your system or the CLI will fall back to the default shell detection.

Checkpointing:

By default, Cosine CLI creates a checkpoint at the end of each agent turn, committing only the files the agent edited. Each checkpoint is a lightweight git commit that you can revert or reapply from the timeline. To disable this globally:

[config]
checkpointing = false

You can also disable it per session with the `—checkpointing=false` flag:

cos start --checkpointing=false

Browser ([browser])

Chrome DevTools Protocol (CDP) configuration for browser automation.

Field	Type	Description
cdp_url	string	URL to Chrome’s debugging port (e.g., http://localhost:9222)

MCP ([mcp])

Model Context Protocol server configurations. See MCP Configuration for detailed documentation.

[mcp.servers.myserver]
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path"]

Repository Agent ([agent])

Settings for the AI agent in this specific repository.

Field	Type	Description
model	string	Override the default model for this repo
extra_context	string	Path to a markdown file to append to system prompts

Hooks ([hooks])

Automated actions triggered by CLI events.

Field	Type	Description
on_save	string	Shell command to run after file writes

on_save details:

• Runs via sh -c with working directory set to the config’s directory
• Supports {file} or {{file}} placeholder for the saved file path
• Exposes environment variables:
  • COSINE_ON_SAVE_FILE - Path to the saved file
  • COSINE_ON_SAVE_CONFIG - Path to the config file

Example with placeholder:

[hooks]
on_save = "go test ./... -run TestRelatedTo{file}"

Telemetry ([telemetry])

Control usage data collection.

Field	Type	Default	Description
enabled	bool	true	Enable/disable telemetry

Note

Telemetry helps us improve Cosine by collecting anonymous usage data. No code or personal information is transmitted.

Environment Variables

COSINE_CONFIG_FILE

Override the default user config file location:

export COSINE_CONFIG_FILE=/path/to/custom/config.toml
cos start

OPENAI_API_KEY / Custom Keys

Some MCP servers require their own API keys as environment variables:

export OPENAI_API_KEY=sk-...
cos start

Command-line Flags Reference

All available global flags:

Flag	Short	Description	Default
--inference	-i	Inference base URL	From config
--system-prompt	-s	System prompt ID	lumen
--prompt	-p	One-shot prompt	-
--cwd	-	Working directory	.
--api-key	-k	API token	From config
--auto-accept-plans	-	Auto-accept plans	false
--auto-accept	-	Auto-accept all	false
--checkpointing	-	Enable checkpointing	true
--debug	-	Debug mode	false
--forceUpdate	-	Force update flow	false
--lsp-diagnostics-on-file-read	-	Include LSP diagnostics	false
--profile	-	Config profile	-
--workspace	-	Workspace mode	os
--worktree-name	-	Worktree name	-
--endpoint	-	API endpoint URL	From config
--cdp-url	-	Chrome CDP URL	From config
--model	-	Model override	From config
--reasoning	-	Reasoning level	From config

Complete Configuration Example

A comprehensive example showing all configuration options:

~/.cosine.toml:

[auth]
user_id = "usr_123456789"
token = "tok_abcdef123456"

[api]
base_url = "https://api.cosine.wtf"

[inference]
base_url = "https://api.cosine.wtf"
model = "lumen"
max_context_tokens = 128000
max_turns = 50

[config]
system_prompt_id = "lumen"
latex_formatting = false
reasoning_level = "high"

[browser]
cdp_url = "http://localhost:9222"

[telemetry]
enabled = true

cosine.toml (in repo):

is_topmost_config = true

[agent]
model = "codex"
extra_context = "AGENTS.md"

[hooks]
on_save = "npm run lint -- --fix {file}"

Configuration Tips

1. Keep Secrets in User Config

Don’t commit API tokens to version control. Put them in ~/.cosine.toml, not cosine.toml.

2. Use Profiles for Context Switching

Create different profiles for work vs. personal projects:

# Work profile with work settings
cos --profile work start

# Personal profile with personal preferences
cos --profile personal start

3. Override per Session

Use flags for temporary overrides without changing config files:

# Use a different model just for this session
cos start --model codex

# Debug mode for troubleshooting
cos start --debug

4. Topmost Config for Monorepos

In monorepos, mark the root config as topmost:

# In root cosine.toml
is_topmost_config = true

# CLI won't look above this directory for config

5. Validate Your Config

Test your configuration:

# Start with debug mode to see loaded config
cos start --debug

# Check if MCP servers load correctly
cos start  # Look for MCP status in the TUI

Next Steps

• MCP Configuration - Connect external tools
• Browser Automation - Configure Chrome CDP
• Skills - Manage reusable skill packages