@cogitator-ai/cli

Command-line interface for the Cogitator AI agent runtime. Scaffold projects and grow them with cogitator add, debug them in Cogitator Studio, give coding agents the docs over MCP, check that a project can run, score it with evals, run assistants in the foreground or as a background service, chat with agents from the terminal, manage Ollama models and Docker services, and deploy.

Installation

# Global installation (recommended)
pnpm add -g @cogitator-ai/cli

# Or use with npx
npx @cogitator-ai/cli <command>

Requires Node.js 22.12+.

Full reference: cogitator.app/docs/cli

Quick Start

There are two ways to build an assistant:

# A) Config-driven personal assistant (no code)
cogitator wizard        # answers → cogitator.yml + .env
cogitator up            # run it

# B) Code-first project
npx create-cogitator-app my-assistant   # or: cogitator init my-assistant for a messaging bot
cd my-assistant
pnpm dev
cogitator dev           # Cogitator Studio: chat, traces, approvals, workflows, forks

Quick one-off chat with any model:

cogitator run -m ollama/llama3.1:8b "What is the capital of France?"

Commands

| Command | Description | | -------------------------- | --------------------------------------------------------------------------------------------------------------- | | cogitator init [name] | Scaffold a messaging assistant project (the channels preset of create-cogitator-app) | | cogitator add [features] | Add rag, mcp, workflows, evals, memory, deploy and the other generated features to a project | | cogitator dev | Open Cogitator Studio for the project | | cogitator mcp | Serve the Cogitator docs and the project to coding agents over MCP (stdio) | | cogitator doctor | Check that a project can run: Node, packages, config, keys, models and services | | cogitator eval [files] | Run the eval suites and fail when an assertion fails | | cogitator wizard | Interactive setup that writes cogitator.yml + .env | | cogitator up | Run the assistant from cogitator.yml, or start Docker services | | cogitator down | Stop Docker Compose services | | cogitator assistant | Run a gateway module (src/gateway.ts) with a live dashboard | | cogitator run [msg] | Chat with an agent (one-shot or interactive REPL) | | cogitator build | Bundle a gateway into a self-starting dist/cogitator.mjs | | cogitator daemon <cmd> | Run in the background / install as a launchd or systemd service | | cogitator skill <cmd> | Create, validate, install and remove skills | | cogitator models | List or pull Ollama models | | cogitator status | Show Docker Compose and Ollama status (alias: ps) | | cogitator logs | View Docker Compose service logs | | cogitator deploy | Deploy with Docker or Fly.io (see @cogitator-ai/deploy) |

Every command ends with examples in its --help.

Output and exit codes

Every command exits with 0 when it did what was asked, 1 when it could not (a failed check, deploy or install, a missing service) and 2 when the command line is wrong (an unknown option, command or value, with the closest valid name). Failures print the message and what to do about it on stderr; COGITATOR_DEBUG=1 adds the stack trace. With --json (add, doctor, eval, models, status, deploy) the result goes to stdout as JSON, and a failure as { "ok": false, "error": { "message", "exitCode", "hints" } }.

cogitator init

Creates a messaging assistant project: the channels preset of create-cogitator-app, generated by the same engine, with the provider, model, channels and memory you choose.

cogitator init my-assistant            # prompts for provider, model, channels, memory
cogitator init my-assistant --no-install --no-git --no-telemetry

The prompts cover the LLM provider (Anthropic, OpenAI, Google or Ollama) and model, channels (Telegram, Discord, Slack, WebChat, Bluesky, Threads) with their tokens, and the memory adapter (SQLite, in-memory or Postgres). Tokens and keys go to .env (mode 600). The project is the same as npx create-cogitator-app my-assistant --preset channels: the registry in src/cogitator.ts, tests on a mocked model, cogitator.yml, AGENTS.md, Cogitator Studio and the rest. The assistant is src/gateway.ts, the gateway export that cogitator assistant, cogitator build and cogitator daemon run, and src/index.ts starts it for dev and start. When the project has compose services (Postgres memory, the Ollama container) and Docker is running, it offers to start them the way create-cogitator-app does, before it prints the next steps. A Postgres URL of your own leaves the compose Postgres out.

cogitator add

cogitator add rag                       # answers grounded in docs/
cogitator add workflows evals           # two features at once
cogitator add --memory postgres         # switch the memory adapter
cogitator add --deploy docker --dry-run # every diff, nothing written
cogitator add --agent claude            # MCP config and skill for Claude Code

Grows a project created by create-cogitator-app or cogitator init with the same feature modules that generated it: the project and its extended spec are both planned, and what the addition changes between them is merged into the files on disk. Files still as generated (by the hashes in .cogitator/scaffold.json) take the change; package.json, cogitator.yml, docker-compose.yml and pnpm-workspace.yaml merge key by key, keeping your values and comments; the managed block of AGENTS.md is rewritten and the rest kept; .gitignore gains missing lines; an edited README is left with a note. Any other file you edited that the addition changes is a conflict: nothing is written, and the change is printed as a diff. Adding what the project has is a no-op. New dependencies are installed (--no-install skips it), the written files formatted, and the new spec and command recorded in package.json.

cogitator dev

cogitator dev                         # http://localhost:4321, opens the browser
cogitator dev --port 4400 --no-open
cogitator dev --host 0.0.0.0          # reachable from your network, with a token in the URL

Opens Cogitator Studio for the project in the current directory: chat with every agent of src/cogitator.ts (streamed answers, reasoning, tool calls, stop, threads), approve tool calls that need it, read the waterfall trace of each run with nested agents, tokens and cost per model call, run workflows with live node statuses and rerun them from a node, and fork a run from any step with a changed input or tool result. The project runs in a child process that reloads when you save (--no-watch turns it off). History lives in .cogitator/studio/.

cogitator mcp

A stdio MCP server for Claude Code, Cursor and Codex, configured by create-cogitator-app --agent or cogitator add --agent:

| Tool | What it does | | ----------------- | ------------------------------------------------------------------------------------------ | | search_docs | Searches the docs bundled with the installed @cogitator-ai/core, best passages first | | read_doc | Reads a page, or one section with path#section | | inspect_project | The agents (model, instructions, tool schemas), workflows and swarms of src/cogitator.ts | | check_project | Runs cogitator doctor, offline unless asked |

The registry loads in a child process, so the agent always sees the current code and the project's own output never reaches the MCP stream. The server finds the project from a subdirectory, or takes --project <dir>.

cogitator doctor

cogitator doctor            # Node, packages, cogitator.yml, keys, services, models
cogitator doctor --offline  # no provider or service probes
cogitator doctor --json

Checks the Node version against engines, the installed @cogitator-ai/* packages, cogitator.yml, the variables src/env.ts requires, the provider key (with a cheap call), Redis, Postgres and the other services the config uses, and the Ollama models. Each problem comes with the fix; it exits 1 when one fails.

cogitator eval

cogitator eval                                   # every evals/*.eval.ts
cogitator eval evals/answers.eval.ts --max-cases 5
cogitator eval --json --report eval-report.json  # for CI
cogitator eval --skip-without-key                # exit 0 on forks without the key

Runs eval suites (files exporting an EvalSuite from @cogitator-ai/evals as default) and exits 1 when an assertion fails or every case errored.

cogitator wizard

Interactive setup for the config-driven personal assistant run by cogitator up.

cogitator wizard          # create cogitator.yml (+ .env)
cogitator wizard --edit   # edit an existing cogitator.yml, pre-filling current values

The wizard asks for your name and the assistant's name, the LLM provider and model (models are fetched live from the provider registry or your Ollama server), channels (Telegram, Discord, Slack, Bluesky, Threads with owner IDs), capabilities (web search, file system, GitHub, device tools, browser, scheduler, RAG, self-config, self-tools), MCP servers (quoted arguments are supported), the SQLite memory path and the assistant's personality. A terminal channel is always available.

Secrets are merged into .env without touching your other variables or comments. In --edit mode, leaving a secret blank keeps the current value, and existing MCP servers and advanced settings (security, rate limits, …) are preserved. The wizard does not ask about WhatsApp, WebChat or Postgres memory, but keeps them: channels.whatsapp / channels.webchat entries stay as they are, and a memory.adapter: postgres config is kept (the SQLite path prompt is skipped).

See the wizard guide for the generated cogitator.yml.

cogitator up / down

cogitator up                       # ./cogitator.yml (or .yaml) → run the assistant
cogitator up -c path/to/assistant.yml
cogitator up --no-restart-loop     # run in-process, without the restart supervisor

When a cogitator.yml exists, up validates it (errors list the offending fields), loads the .env next to it into process.env without overriding variables that are already set (so tools that read process.env, such as web_search and github_api, see the wizard's keys) and starts the assistant. Unless --no-restart-loop is given, up runs the assistant in a child process and starts it again whenever it exits with code 78 — the owner /restart command and self-config updates; SIGINT/SIGTERM are forwarded for a graceful shutdown. With --no-restart-loop the assistant runs in the up process and simply stops on /restart.

A cogitator.yml made only of @cogitator-ai/config runtime keys (llm.defaultModel, memory, sandbox, … — the file create-cogitator-app generates) is not an assistant config: your project's code loads it. up then starts the project's Docker Compose services, or, without a compose file, exits explaining that you start the project itself (e.g. pnpm dev). up -c with such a file fails with the same explanation, and cogitator daemon skips it when auto-detecting what to run.

Without an assistant config, up manages the Docker Compose project found in the current or a parent directory (docker-compose.yml, compose.yml, …):

| Option | Default | Description | | -------------- | ------- | ---------------------------------- | | -d, --detach | true | Run services in background | | --no-detach | - | Run services in foreground | | --pull | false | Pull latest images before starting |

After starting, the published ports of every service are printed.

cogitator down             # stop services (keep data)
cogitator down --volumes   # stop and delete volumes

cogitator assistant

Runs a module that exports a gateway (as generated by init) with a live dashboard.

cogitator assistant                    # src/gateway.ts
cogitator assistant -c src/my-gw.ts
cogitator assistant --quiet            # no banner, status line or hotkeys (used by the daemon)

TypeScript modules are loaded through tsx, resolved from your project first. .env in the working directory is loaded before the module. Hotkeys (interactive terminals only): s sessions, c channels, h help, q quit.

cogitator run

Run an agent with a message, or start an interactive REPL when no message is given.

cogitator run "Explain quantum computing in simple terms"
cogitator run -m openai/gpt-6.1-sol "Analyze this code..."
cogitator run --no-stream "Hello"
cogitator run            # interactive

| Option | Default | Description | | --------------------- | ----------- | ----------------------------------- | | -c, --config <path> | auto | Config file (must exist when given) | | -m, --model <model> | auto-detect | Model, e.g. ollama/qwen3:8b | | -i, --interactive | false | Force interactive mode | | -s, --stream | true | Stream response tokens | | --no-stream | - | Disable streaming |

Config resolution: -c → COGITATOR_CONFIG → cogitator.yml, cogitator.yaml, .cogitator.yml, .cogitator.yaml, cogitator.json. The .env next to the file (or in the working directory without one) is loaded first, without overriding variables already set. The file is loaded with @cogitator-ai/config, so ${ENV} references and COGITATOR_* / provider environment variables apply even without a file. An assistant config from cogitator wizard is not a runtime config: run takes its llm.provider and llm.model as the model and everything else from the environment (cogitator up runs the assistant itself).

Model resolution: -m → COGITATOR_MODEL → llm.defaultModel from the config → the model of an assistant config → first installed Ollama model (preferring qwen3:8b, qwen3.5:9b, llama3.1:8b, llama3:8b, gemma3:4b, gemma2:9b, mistral:7b). Ollama is reached at llm.providers.ollama.baseUrl, OLLAMA_URL or OLLAMA_HOST.

Interactive commands: /model [name], /clear, /help, exit / quit (Ctrl+D also exits).

cogitator build

Bundles a gateway module with esbuild into a single self-starting ES module. The bundle starts the exported gateway and stops it gracefully on SIGINT/SIGTERM. esbuild ships with the CLI, so the project needs no extra dependency.

cogitator build                     # src/gateway.ts → dist/cogitator.mjs
cogitator build -c src/gw.ts -o out/bot.mjs --minify --no-sourcemap
node dist/cogitator.mjs

| Option | Default | | ---------------------- | -------------------- | | -c, --config <path> | src/gateway.ts | | -o, --outfile <path> | dist/cogitator.mjs | | --target <version> | node22 | | --sourcemap | true | | --minify | false | | -q, --quiet | false |

Only the project's own code is bundled: every package stays an import resolved from node_modules at runtime, since packages ship native addons (better-sqlite3, the ssh2 behind the Docker sandbox) and optional drivers loaded on demand. Run the bundle where the project's dependencies are installed.

cogitator daemon

Runs your assistant in the background. The entry is auto-detected in this order: dist/cogitator.mjs (from cogitator build), an assistant cogitator.yml / cogitator.yaml (via cogitator up; a runtime config is skipped), src/gateway.ts (via cogitator assistant --quiet). Use -c to choose explicitly.

cogitator daemon start [-c <entry>]
cogitator daemon status          # PID, uptime, memory
cogitator daemon logs -f -n 100  # .cogitator/daemon.log
cogitator daemon restart [-c <entry>]
cogitator daemon stop            # SIGTERM, then SIGKILL after ~10s

cogitator daemon install [-c <entry>]   # launchd (macOS) or systemd --user (Linux)
cogitator daemon uninstall

The PID file (.cogitator/daemon.pid) records the launched script, so stop never signals an unrelated process that reused the PID. Service definitions use absolute paths, the current PATH, and start on login (loginctl enable-linger keeps a systemd user service running after logout).

cogitator skill

cogitator skill create weather-api --template api   # basic | device | api; --global for ~/.cogitator/skills
cogitator skill validate skills/weather-api         # defaults to the current directory
cogitator skill list
cogitator skill add ./path/to/skill [--global]
cogitator skill remove weather-api [--global]

Local skills live in ./skills, global ones in ~/.cogitator/skills. Skill names must be kebab-case. validate loads skill.ts/skill.js/skill.mjs, checks the defineSkill shape and every tool, required environment variables (env) and that dependencies resolve from the skill's location; it exits non-zero on problems.

cogitator models

cogitator models                       # list installed models
cogitator models --pull qwen2.5:0.5b   # pull with progress
cogitator models --url http://gpu-box:11434
cogitator models --json                # name, size and date of each model

The Ollama URL defaults to OLLAMA_BASE_URL, then OLLAMA_URL, then OLLAMA_HOST (read like Ollama reads it: port 11434 when none is given, 0.0.0.0 as localhost), then http://localhost:11434, OLLAMA_API_KEY is sent as a bearer token. Pull errors reported by Ollama (e.g. unknown model) fail the command.

cogitator status / logs

cogitator status          # compose services (state, health) + Ollama reachability
cogitator status --json
cogitator logs ollama -f -t -n 50
cogitator logs -n all

| Option | Default | Description | | -------------------- | ------- | --------------------------------- | | [service] | all | Service name (redis, postgres, …) | | -f, --follow | false | Follow log output | | -n, --tail <lines> | 100 | Number of lines, or all | | -t, --timestamps | false | Show timestamps |

status still reports Ollama when Docker is not running.

cogitator deploy

cogitator deploy --dry-run          # analyze + preflight only
cogitator deploy --dry-run --json   # the plan for scripts and CI: secrets, services, warnings, checks
cogitator deploy                    # docker: build image, start compose stack
cogitator deploy --target fly --region ord
cogitator deploy --registry ghcr.io/acme   # build + push (use --no-push to skip)
cogitator deploy status
cogitator deploy destroy

| Option | Description | | ----------------------- | ---------------------------------------- | | -t, --target <target> | docker (default) or fly | | -c, --config <path> | Config file to deploy from | | --registry <url> | Container registry to push to | | --no-push | Skip pushing even when a registry is set | | --dry-run | Show the plan without executing | | --region <region> | Deploy region (Fly.io) | | --json | The plan, result or status as JSON |

The model, memory and deploy: section all come from one config file: the -c file, else the first of cogitator.yml, cogitator.yaml, .cogitator.yml, .cogitator.yaml. The plan lists the kind (server or worker), detected services (marked as not provisioned on Fly, where REDIS_URL / DATABASE_URL are required instead), volumes, required secrets (read from the environment or the project's .env), warnings and preflight checks. On Docker the deploy only succeeds when the app container keeps running after it starts, otherwise its last log lines are shown. See @cogitator-ai/deploy and the deploy guide for details.

Environment Variables

| Variable | Used by | Description | | ------------------------------------------------------- | ------------------------- | ----------------------------------- | | COGITATOR_CONFIG | run | Config file path | | COGITATOR_MODEL | run | Default model | | OLLAMA_URL / OLLAMA_HOST | run, models, status | Ollama endpoint | | OLLAMA_API_KEY | run, models, wizard | Ollama Cloud / authenticated Ollama | | OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY | run, init, wizard | Provider keys | | COGITATOR_DEBUG | all | Print stack traces | | COGITATOR_TELEMETRY_DISABLED, DO_NOT_TRACK | init | Send no anonymous usage event |

See @cogitator-ai/config and the configuration guide for every COGITATOR_* variable.

License

MIT