CLI Reference

This is the reference page for commands run from a shell. Interactive slash commands and power commands live in Commands; this page covers the Symfony Console command surface exposed by kosmo and bin/kosmo.

Most automation-oriented commands support --json. Prefer JSON mode for agents, scripts, CI, wrappers, and tests because failures return structured success: false envelopes where the command owns the error handling.

Global Options

Symfony global options are accepted by every command:

Option	Purpose
-h, --help	Show help for a command.
-q, --quiet	Only show errors.
-v, -vv, -vvv	Increase verbosity.
-V, --version	Print application version.
--ansi, --no-ansi	Force or disable ANSI output.
-n, --no-interaction	Never ask interactive questions.

Shell completion is built in:

kosmokrator completion zsh
eval "$(kosmokrator completion zsh)"

Agent Command

agent is also the default command, so kosmo -p "task" and kosmokrator agent -p "task" are equivalent.

kosmokrator [options] [prompt]
kosmokrator agent [options] [prompt]

Option	Values	Purpose
--renderer	auto, tui, ansi	Select terminal renderer.
--no-animation	flag	Skip startup animation.
--resume	flag	Resume last session for this project.
--session	session ID or prefix	Resume a specific session.
-p, --print	flag	Run headlessly and exit.
-o, --output-format	text, json, stream-json	Select headless output format.
-m, --model	model ID	Override configured model.
--mode	edit, plan, ask	Select agent mode.
--permission-mode	guardian, argus, prometheus	Select permission mode.
--yolo	flag	Alias for --permission-mode prometheus.
-t, --max-turns	integer	Cap agentic LLM turns.
--timeout	seconds	Cap wall-clock runtime.
-c, --continue	flag	Continue the most recent session.
--append-system-prompt	text	Append extra instructions to the default prompt.
--system-prompt	text	Replace the system prompt for this run.
--no-session	flag	Do not persist this run.

Examples:

kosmo
kosmo --renderer=ansi --no-animation
kosmo -p "Explain this repository" --mode ask --output-format text
kosmo -p "Run tests and fix failures" --mode edit --permission-mode guardian
kosmo -p "Review the branch" --mode plan --output-format json --no-session
kosmo -p "Summarize progress" --continue --output-format stream-json

Setup, Auth, And Config

Command	Purpose
setup	Interactive or headless first-run provider/model setup.
auth	Provider auth status, login, and logout.
config	Inspect and update settings through the legacy config facade.
settings:*	Schema-backed headless settings API.
secrets:*	Managed secret storage helpers.
providers:*	Provider discovery, model discovery, credentials, and custom providers.
codex:*	ChatGPT OAuth helpers for the Codex provider.

setup

kosmo setup
kosmo setup --provider openai --model gpt-5.4-mini --api-key-env OPENAI_API_KEY --global --json
printf %s "$ANTHROPIC_API_KEY" | kosmo setup --provider anthropic --api-key-stdin --json
kosmo setup --provider codex --device --json

Options: --renderer, --no-animation, --provider, --model, --api-key, --api-key-stdin, --api-key-env, --device, --global, --project, --json.

auth

kosmo auth status --json
kosmo auth status openai --json
kosmo auth login openai --api-key-env OPENAI_API_KEY --json
printf %s "$OPENAI_API_KEY" | kosmo auth login openai --api-key-stdin --json
kosmo auth login codex --device
kosmo auth logout openai --json

Actions: status, login, logout.

config

kosmo config show
kosmo config show --json
kosmo config paths --json
kosmo config get agent.default_model --json
kosmo config set agent.default_model gpt-5.4-mini --provider openai --global --json
kosmo config unset agent.mode --project --json
kosmo config edit --project

Actions: show, get, set, unset, edit, paths.

Prefer settings:* for new automation because it exposes categories, types, current source, effect timing, and validation metadata.

Settings Commands

Command	Purpose
settings:list	List all headless-configurable settings.
settings:get	Read one effective setting.
settings:set	Write one setting.
settings:unset	Remove an override.
settings:apply	Apply a JSON batch.
settings:options	Show valid options for choice settings.
settings:doctor	Diagnose headless readiness.
settings:examples	Print machine-readable examples.

kosmo settings:list --json
kosmo settings:list --category permissions --json
kosmo settings:get tools.default_permission_mode --json
kosmo settings:options agent.default_model --provider openai --json
kosmo settings:set agent.mode plan --project --json
kosmo settings:set tools.denied_tools "file_write,bash" --global --json
kosmo settings:unset agent.mode --project --json

jq -n '{
  settings: {
    "agent.default_provider": "openai",
    "agent.default_model": "gpt-5.4-mini",
    "tools.default_permission_mode": "guardian"
  }
}' | kosmo settings:apply --stdin-json --global --json

See Settings Reference for the full schema.

Provider Commands

Command	Purpose
providers:list	List providers, labels, source, auth mode, and configured status.
providers:models <provider>	List models for one provider.
providers:status [provider]	Show credential/configuration status.
providers:configure <provider>	Configure provider credentials and default model.
providers:logout <provider>	Clear stored provider credentials.
providers:custom:list	List custom providers.
providers:custom:upsert [id]	Create or update a custom provider.
providers:custom:delete <id>	Delete a custom provider.

kosmo providers:list --json
kosmo providers:models anthropic --json
kosmo providers:status openai --json
printf %s "$OPENAI_API_KEY" | \
  kosmo providers:configure openai --api-key-stdin --model gpt-5.4-mini --global --json
kosmo providers:configure codex --device --global --json
kosmo providers:logout openai --json

Custom OpenAI-compatible provider:

kosmo providers:custom:upsert local_ollama \
  --driver openai-compatible \
  --url http://127.0.0.1:11434/v1 \
  --model qwen3:32b \
  --label "Local Ollama" \
  --global \
  --json

Custom provider options: --driver, --url, --auth, --model, --label, --context, --max-output, --api-key, --api-key-stdin, --api-key-env, --stdin-json, --global, --project, --json.

Secrets Commands

Command	Purpose
secrets:list	List managed secret statuses.
secrets:status <key>	Show whether one secret is configured.
secrets:set <key> [value]	Store a secret.
secrets:unset <key>	Remove a secret.

printf %s "$OPENAI_API_KEY" | kosmo secrets:set provider.openai.api_key --stdin --json
kosmo secrets:status provider.openai.api_key --json
kosmo secrets:list --json
kosmo secrets:unset provider.openai.api_key --json

Use --stdin or --env for automation. Avoid putting secrets directly in argv because shell history and process listings may capture them.

Integration Commands

Integrations are discovered from installed OpenCompany integration packages and exposed through both generic and provider-specific commands.

Command	Purpose
integrations:list	List providers and functions.
integrations:status	Show activation, credentials, accounts, and permission state.
integrations:search <query>	Search functions.
integrations:docs [page]	Read provider/function docs.
integrations:fields <provider>	Show credential fields.
integrations:doctor [provider]	Diagnose readiness and next steps.
integrations:configure <provider>	Configure credentials, activation, accounts, and permissions.
integrations:schema <provider.function>	Print JSON input schema.
integrations:examples <page>	Show usage examples.
integrations:call <provider.function>	Call any function.
integrations:lua [file]	Run Lua against configured integrations and MCP servers.
integrations:<provider> [function]	Dynamic provider shortcut, for example integrations:plane.

kosmo integrations:list --json
kosmo integrations:search "plane issue" --json
kosmo integrations:docs plane.create_issue --format markdown
kosmo integrations:schema plane.create_issue
kosmo integrations:configure plane --set api_key="$PLANE_API_KEY" --enable --read allow --write ask --json
kosmo integrations:call plane.list_issues '{"project_id":"..."}' --json
kosmo integrations:plane list_issues --project-id=... --json
kosmo integrations:lua workflow.lua --force --json

Installed dynamic shortcuts currently include integrations:clickup, integrations:coingecko, integrations:plane, and integrations:plausible in this checkout. The set changes with installed integration packages.

See Integrations for argument coercion, multi-account credentials, Lua helpers, permissions, and result envelopes.

MCP Commands

MCP servers are configured in portable mcpServers JSON files, with compatibility for VS Code/Cursor servers files.

Command	Purpose
mcp:list	List configured servers.
mcp:status [server]	Show server readiness.
mcp:add <name>	Add or update a server.
mcp:remove <name>	Remove a server.
mcp:enable <name> / mcp:disable <name>	Toggle a server.
mcp:trust <server>	Trust a project server command after review.
mcp:tools [server]	Discover tools.
mcp:schema <server.tool>	Show tool schema.
mcp:call <server.tool>	Call a tool.
mcp:<server> <tool>	Dynamic server shortcut.
mcp:lua [file]	Run Lua against MCP servers.
mcp:resources <server> / mcp:resource <server> <uri>	List or read resources.
mcp:prompts <server> / mcp:prompt <server> <prompt>	List or get prompts.
mcp:secret:set, mcp:secret:list, mcp:secret:unset	Store MCP secret values.
mcp:import <path>	Import .mcp.json, VS Code, Cursor, or mcpServers JSON.
mcp:export	Export effective config.
mcp:preset	List or install known presets.
mcp:examples	Print examples.
mcp:doctor	Diagnose MCP readiness.

kosmo mcp:add github --type stdio --command github-mcp-server \
  --env GITHUB_TOKEN --read allow --write ask --project --json
kosmo mcp:trust github --project --json
kosmo mcp:tools github --json
kosmo mcp:schema github.search_repositories --json
kosmo mcp:call github.search_repositories --query kosmokrator --json
kosmo mcp:github search_repositories --query kosmokrator --json
kosmo mcp:lua workflow.lua --json

Use --force on discovery/call/Lua commands only for trusted automation. It bypasses MCP trust and read/write policy for that one command.

Web Commands

Command	Purpose
web:providers	List optional external web providers.
web:configure <provider>	Configure provider credentials and defaults.
web:doctor	Diagnose web-provider setup.
web:search <query>	Run an external search provider.
web:fetch <url>	Fetch or extract a URL through a provider.
web:crawl <url>	Crawl a site through Tavily or Firecrawl.

kosmokrator web:providers --json
kosmokrator web:configure tavily --api-key-env TAVILY_API_KEY --enable --search --global --json
kosmokrator web:search "KosmoKrator terminal agent" --max-results 5 --json
kosmokrator web:fetch https://example.com --format markdown --json
kosmokrator web:crawl https://docs.example.com --max-pages 10 --json

See Web Providers for provider capabilities, environment variables, and settings.

Telegram Gateway Commands

Command	Purpose
gateway:telegram	Run the gateway worker.
gateway:telegram:configure	Configure the worker headlessly.
gateway:telegram:status	Show readiness and effective config.
gateway:telegram:worker	Internal worker command.

printf %s "$TELEGRAM_BOT_TOKEN" | \
  kosmo gateway:telegram:configure --token-stdin --enabled on --global --json
kosmo gateway:telegram:configure --allowed-users "12345,@alice" --require-mention on --json
kosmo gateway:telegram:status --json
kosmo gateway:telegram

See Telegram Gateway for routing, security, and deployment notes.

ACP And Maintenance

Command	Purpose
acp	Start the Agent Client Protocol stdio server.
update	Check for and apply release updates when supported.
smoke:startup	Offline startup checks for CI and release artifacts.
codex:login / codex:status / codex:logout	Codex provider OAuth helpers.

kosmo acp --cwd /path/to/project --mode edit --permission-mode guardian
kosmo update --check
kosmo update --yes
kosmokrator smoke:startup --json

JSON And Exit Codes

Automation commands generally follow this shape:

{
  "success": true,
  "data": {},
  "meta": {}
}

On failure they return a non-zero exit code and include an error field when JSON mode is enabled. Headless agent --output-format json returns a run result with text, session ID, duration, usage, turn count, tool-call count, success, exit code, and error.

For long-running headless agent runs, prefer --output-format stream-json when a wrapper needs progress:

kosmo -p "Run tests and fix failures" --output-format stream-json | jq -c .