CLI Reference

All commands are invoked via the main entry-point:

python -m codumentor.cli.main [GLOBAL OPTIONS] <command> [COMMAND OPTIONS]

Use --help on any command to see the exhaustive list.

Global Options (available before the command name)

Flag	Description
`-c, --config PATH`	Path to `codumentor.yaml` (default: `codumentor.yaml`). Can be specified multiple times to deep-merge config files, with later files taking precedence.
`--log-level LEVEL`	Override base log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`).
`--logger-log-level logger:LEVEL`	Set log level per logger (repeatable, e.g. `codumentor.tools:DEBUG`).
`--model NAME`	Override chat model.
`--agent-base-url URL`	Override chat endpoint.
`--api-key KEY`	General API key (fallback for all models). Supports `${ENV_VAR}` syntax.
`--agent-api-key KEY`	Agent-specific API key. Supports `${ENV_VAR}` syntax.
`--embedding-api-key KEY`	Embedding-specific API key. Supports `${ENV_VAR}` syntax.
`--max-iterations N`	Limit LLM/tool iterations per query. (`--max-turns` is a deprecated alias.)
`--repos-dir DIR`	Base directory for cloned repositories.
`--print, -p`	Non-interactive mode: run a single query and exit. Pass the query as a positional argument after the flags, e.g. codumentor -p "Explain auth flow"
`--verbose`	Enable verbose (DEBUG) logging; shorthand for `--log-level DEBUG`.
`--output-format FORMAT`	Output format: `text` (default) or `json`.
`--prompt-dir DIR`	Location of prompt templates (Jinja2). Overrides `prompt.template_dir` from config. See Prompt System.
`--debug / --no-debug`	Enable/disable debug mode for prompt templates (independent of log level).
`--disable-streaming / --enable-streaming`	Disable/enable streaming responses during TUI and print-mode (`-p`) operations. When disabled, responses are returned as complete messages after processing.

Everything else — embedding model, vector DB path, shell timeouts, output-size caps, log file paths, and the like — is configured via codumentor.yaml. See configuration reference for the full schema.

By default, CLI and TUI send application logs only to the configured log file (not to stderr), so printed answers and the TUI stay readable. The codumentor api command and other API entrypoints log to stderr and the file. Override either behavior for all modes with logging.console in YAML (true / false); see logging options in the full configuration reference.

Configuration File Merging

The --config option can be specified multiple times to merge configuration files. Files are deep-merged from left to right, with later files taking precedence over earlier ones.

# Use multiple config files - development.yaml overrides base.yaml
python -m codumentor.cli.main --config base.yaml --config development.yaml -p "What is Junior?"

# Environment-specific overrides
python -m codumentor.cli.main -c codumentor.yaml -c production.yaml api

# Layer multiple configurations (launches the TUI)
python -m codumentor.cli.main -c base.yaml -c team-settings.yaml -c personal.yaml

Example: If base.yaml contains:

repos:
  - https://github.com/org/repo1.git
models:
  agent: "gpt-4"
  embedding: "text-embedding-ada-002"

And override.yaml contains:

repos:
  - https://github.com/org/repo2.git
models:
  agent: "gpt-4-turbo"

The merged result will be:

repos:
  - https://github.com/org/repo2.git  # Overridden completely
models:
  agent: "gpt-4-turbo"               # Overridden
  embedding: "text-embedding-ada-002" # Preserved from base

API Key Configuration

API keys can be configured via configuration files, environment variables, or CLI options. CLI options support environment variable substitution using ${VARIABLE_NAME} syntax.

# Use environment variable substitution in CLI
python -m codumentor.cli.main --api-key '${OPENAI_API_KEY}' -p "What is Junior?"

# Use different API keys for different model types (launches the TUI)
python -m codumentor.cli.main \
  --agent-api-key '${OPENROUTER_API_KEY}' \
  --embedding-api-key '${GOOGLE_API_KEY}'

# Literal API key (not recommended for security)
python -m codumentor.cli.main --api-key 'sk-1234567890abcdef' -p "test"

Security Note: When using literal API keys in CLI commands, they may be visible in process lists and shell history. Use environment variables or configuration files for better security.

Commands

`config`

Display the current configuration (after CLI overrides).

python -m codumentor.cli.main config [--format yaml|json]

`ingest`

Clone/update repositories and build (or update) the vector database.

Option	Description
`--dry-run`	Simulate Git operations without cloning.
`--recreate`	Drop and rebuild the vector DB from scratch.

To re-ingest automatically on every push instead of running this by hand, configure push webhooks.

`tui` (default)

Launch the terminal UI — the interactive console surface for Codumentor. This is the default command: running codumentor with no subcommand launches the TUI.

Option	Description
`-m, --message TEXT`	Send messages automatically as initial messages (repeatable). Available both on the `tui` subcommand and at the top level when no subcommand is given.
`-r, --resume ID`	Resume a previous TUI conversation by ID/prefix, or `last` for the most recent one.
`--list-sessions`	List recent resumable TUI conversations, then exit.

Examples:

# Launch the TUI (default behaviour)
python -m codumentor.cli.main

# Launch the TUI with a single initial message
python -m codumentor.cli.main -m "Hello, can you help me with Python?"

# Launch with multiple initial messages
python -m codumentor.cli.main -m "Hello" -m "How are you?" -m "Can you explain decorators?"

# Resume the most recent conversation
python -m codumentor.cli.main --resume last

# List resumable conversations
python -m codumentor.cli.main --list-sessions

Shell auto-approval is configured via tools.shell_always_allow: true in codumentor.yaml.

Non-interactive mode (`-p` / `--print`)

Run a single query and exit, compatible with the Claude Code CLI convention:

# Run a single query and stream the response
codumentor -p "What does the auth module do?"

# Output as JSON
codumentor -p "What does the auth module do?" --output-format json

# Read prompt from stdin
echo "What does the auth module do?" | codumentor -p

# Pipe with JSON output
echo "What is X?" | codumentor -p --output-format json

# Combine with model override
codumentor --model claude-sonnet-4-6 -p "Summarise this codebase"

JSON output (--output-format json) returns a single object compatible with the Claude Code CLI:

{
  "type": "result",
  "subtype": "success",
  "result": "The auth module handles ...",
  "session_id": "codumentor_a1b2c3...",
  "duration_ms": 4320,
  "model": "gemini-2.0-flash",
  "total_cost_usd": 0.0012,
  "usage": {
    "input_tokens": 1024,
    "output_tokens": 256,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  }
}

`api`

Start the OpenAI-compatible HTTP API server.

Option	Description
`--host TEXT`	Host to bind to (default: 127.0.0.1).
`--port INTEGER`	Port to bind to (default: 2638).
`--reload`	Enable auto-reload for development.

# Start API server on default host/port
python -m codumentor.cli.main api

# Start on custom host/port
python -m codumentor.cli.main api --host 0.0.0.0 --port 8080

# Development mode with auto-reload
python -m codumentor.cli.main api --reload

The API server provides OpenAI-compatible endpoints for integration with tools and applications. See the API Reference for detailed usage information.

`cache stats`

Show embedding cache statistics.

`cache clear`

Clear embedding cache entries. Use --model NAME to target a single model and --confirm to skip the prompt.

`cache cleanup`

Remove embedding cache entries older than N days.

Option	Description
`--days N`	Maximum age (default: 30).
`--dry-run`	Show what would be deleted.

Developer Scripts (not shipped in the built binary)

Some previously-built-in subcommands live as standalone scripts under scripts/. They are source-only — they are not bundled into the release binary and are not exposed by the codumentor CLI. Run them directly with Python:

Knowledge-base search — `scripts/codumentor_search.py`

Search the knowledge base and print raw results exactly as they are presented to the model.

python scripts/codumentor_search.py "What is Junior?"
python scripts/codumentor_search.py "authentication logic" --num-documents 10
python scripts/codumentor_search.py "database connection" -r my-repo -n 8

Options: -c/--config PATH (repeatable), -n/--num-documents N, -r/--repository REPO.

Evaluation harness — `scripts/codumentor_eval.py`

Run agent evaluation on a suite of *.task.yaml files.

python scripts/codumentor_eval.py
python scripts/codumentor_eval.py --suite my_tests --html-report custom_report.html
python scripts/codumentor_eval.py --task "test_*" --judge-model gpt-4
python scripts/codumentor_eval.py --variant fast.yaml --variant slow.yaml \
  --judge-model gpt-4 --judge-api-key '${JUDGE_KEY}'

Judge-specific options (--judge-model, --judge-base-url, --judge-api-key) live on this script because they are only meaningful for the eval harness.

Log viewer — `scripts/logs_viewer/`

Open a JSON log file and serve a web UI for browsing sessions.

python scripts/logs_viewer/__main__.py --log-file logs/codumentor.json --port 1111
# or, as a module:
python -m scripts.logs_viewer --log-file logs/codumentor.json

Options: --log-file PATH, --port N, --static (disable real-time monitoring).

CLI Reference

Global Options (available before the command name)

Configuration File Merging

API Key Configuration

Commands

config

ingest

tui (default)

Non-interactive mode (-p / --print)

api

cache stats

cache clear

cache cleanup