CLI Reference

Every startup flag, every slash command, every environment variable Cogtrix recognises. Sourced from src/cli/args.py and src/cli/commands.py in the Cogtrix repo.

Startup flags

Passed to python cogtrix.py. Long and short forms are equivalent. Repeatable flags accept multiple values.

Getting started

--setup

Setup wizard — generate a config file

--check-config

Validate configuration and exit

--version

Print Cogtrix version and exit

Core

--model NAME alias: -m

Model name or alias from your config (e.g. local, smart, fast).

--session ID alias: -s

Session ID for history. Default: default.

--memory-mode MODE alias: -M

Memory mode: conversation, code, or reasoning. Default: conversation.

--config-file FILE alias: -c

Path to a config file (JSON or YAML).

--data-dir PATH

Root directory for all data storage. Default: data.

Run modes

--prompt TEXT

Run a single prompt, print the response, then exit.

--prompt-file FILE

Read prompt text from a file, then exit.

--no-stream

Disable token streaming. Useful when piping output.

--silent alias: -S

Silent scripting mode — no spinner, no ANSI, plain stdout. Pairs with --prompt.

--assistant

Run as a headless WhatsApp / Telegram daemon. See the Assistant guide.

Assistant mode

--system-prompt TEXT

Custom system prompt that overrides the value from config.

--system-prompt-file FILE

Read the system prompt from a file.

Output and safety

--output FILE alias: -o

Save the response to a file in addition to stdout.

--no-confirm alias: -y

Auto-approve all tool confirmations. Use in trusted contexts only.

--auto-route alias: -R

Route simple queries to a fast model. Requires auto_route_fast_model in config.

--quick alias: -Q

Skip optimizer, memory, and compression. For one-off lookups where latency matters.

--git-native alias: -G

Auto stage and commit after each file write. Requires a git repo.

--no-banner

Suppress the startup banner.

--pipe alias: -I

Read stdin as input. Useful for shell pipelines.

--profile NAME alias: -P

Apply a named config profile defined in the config file.

Logging

--log [FILE]

Write a log file. Default location if no path is given.

--verbose alias: -v

Verbosity level 1 — log LLM interactions.

--debug

Full debug mode — verbosity 2 (LLM interactions + debug logs).

--verbosity N

Set verbosity explicitly: 0, 1, 2, or 3.

Tools

--tools LIST

all, none, minimal, or a comma-separated list of tool names.

--activate-tools LIST

Comma-separated tools to pin as active on startup.

--allow-write-path DIR

Allow file writes to DIR. Repeatable for multiple directories.

--allow-read-path DIR

Allow file reads from DIR. Repeatable.

RAG

--ingest

Build the vector database from --docs-dir and exit.

--docs-dir PATH

Documents directory to ingest. Default: docs.

--vectordb-dir PATH

Vector DB directory. Default: data/vectordb.

--embedding-provider openai|ollama

Embedding provider for ingestion.

--embedding-model NAME

Embedding model name.

Shell completion

--install-completion [SHELL]

Install shell completion. SHELL is one of bash, zsh, fish. Default: auto-detect.

Slash commands

Interactive commands dispatched before any input reaches the LLM. Prefix with /. Use /help <name> for detailed usage and examples.

/help

Show available commands. /help <name> for details.

/quit

Exit the session. Bare exit, quit, q also work.

/info

Show session info — provider, model, memory mode, message count.

/tools

List or manage tools. Subcommands: load, unload, enable, disable.

/mcp

List configured MCP servers. /mcp restart [name] to reconnect.

/clear

Clear conversation history for the current session.

/think

Force the deep-reasoning Tree-of-Thought pipeline on the next prompt.

/delegate

Force task delegation to a sub-agent on the next prompt.

/mode

Show or switch the active memory mode (conversation / code / reasoning).

/memory

Inspect the current session's memory state and tracked entities.

/agents

List or inspect named agents from AGENTS.md.

/tasks

List background tasks. Add an ID to view a specific task.

/spawn

Submit a background task to the task queue.

/goal

Manage session goals (add, list, complete, clear).

/model

Show or switch the active model. Accepts a model name or alias.

/provider

List configured LLM providers.

/session

Show or switch session. Affects which conversation history loads.

/debug

Cycle or set verbosity (0–3) without restarting.

/verbose

Toggle verbose logging on/off.

/approve

Toggle tool auto-approval for the current session.

/optimizer

Toggle the prompt optimizer.

/paste

Enter multi-line paste mode.

/undo

Remove the last exchange (user + assistant) from memory.

/compact

Compress context in place by summarising old messages.

/retry

Re-run the last prompt through the agent.

/setup

Launch the setup wizard mid-session.

/export

Export the current conversation to Markdown or HTML.

/system_prompt

Display the full active system prompt.

Environment variables

Cogtrix reads these at startup. Most are equivalents of CLI flags or standard provider keys.

COGTRIX_CONFIG_FILE

Path to a config file. Equivalent to --config-file.

COGTRIX_OLLAMA

Override the auto-detected Ollama base URL.

OLLAMA_BASE_URL

Standard Ollama env var. Cogtrix respects it.

OPENAI_API_KEY

OpenAI provider key. Recognised at startup.

ANTHROPIC_API_KEY

Anthropic provider key.

GEMINI_API_KEY

Google Gemini provider key.

DEEPSEEK_API_KEY

DeepSeek provider key.

XAI_API_KEY

xAI (Grok) provider key.

COGTRIX_DEBUG

Set to 1 to enable debug logging at process start.

Exit codes

Success.

General error — invalid arguments, unrecoverable runtime error, or unhandled exception.

Configuration error — config file missing, invalid, or fails --check-config.

130

User interrupt (Ctrl-C).