CLI

Command-line interface for the Cogitator AI agent runtime. Scaffold assistant projects, run them in the foreground or as a background service, chat with agents from the terminal, manage Ollama models and Docker services, and deploy.

InstallationCopy Anchor Link

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

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

Requires Node.js 22.12+.

Quick StartCopy Anchor Link

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
cogitator init my-assistant
cd my-assistant
pnpm dev                # or: cogitator assistant

Quick one-off chat with any model:

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

CommandsCopy Anchor Link

Set COGITATOR_DEBUG=1 to print stack traces for unexpected errors.

cogitator initCopy Anchor Link

Creates a TypeScript project with a Gateway wired to your chosen LLM provider, channels and memory adapter.

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

The project name must be a valid npm package name (lowercase, -, _, .) and the directory must not exist yet. The prompts cover the provider (Anthropic, OpenAI, Google or Ollama) and its API key, the default model (listed live from the provider), channels (Telegram, Discord, Slack, WebChat — WebChat when none is picked) and the memory adapter. The package manager used for installation is detected from how you invoked the CLI (pnpm, npm, yarn or bun, otherwise pnpm).

my-assistant/
├── package.json     # @cogitator-ai/* pinned to the versions this CLI ships with
├── tsconfig.json
├── .env             # API keys and channel tokens (mode 0600), when any were entered
├── .gitignore
├── pnpm-workspace.yaml  # allows native builds (better-sqlite3, esbuild, sharp), pnpm only
└── src/
    ├── gateway.ts   # exports `gateway` — agent, channels, memory adapter
    └── agent.ts     # starts the gateway (pnpm dev / pnpm start)

src/gateway.ts loads .env itself (process.loadEnvFile, Node ≥ 20.12), so it works with pnpm dev, cogitator assistant, cogitator build and the daemon alike.

cogitator wizardCopy Anchor Link

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 the LLM provider and model (models are fetched live from the provider registry or your Ollama server), channels (Telegram, Discord, Slack with owner IDs), capabilities (web search, file system, GitHub, device tools, browser, scheduler, RAG, self-config, self-tools), MCP servers (quoted arguments are supported) and the SQLite memory path.

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).

cogitator up / downCopy Anchor Link

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.

Once the assistant is up, the summary lists the channels that actually started and warns when none did (for example because their tokens are missing from .env).

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.

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

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

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

cogitator assistantCopy Anchor Link

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 runCopy Anchor Link

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

Config resolution: -c → COGITATOR_CONFIG → cogitator.yml, cogitator.yaml, cogitator.json, .cogitator.yml, .cogitator.yaml. The file is loaded with @cogitator-ai/config, so ${ENV} references and COGITATOR_* / provider environment variables apply even without a file.

Model resolution: -m → COGITATOR_MODEL → llm.defaultModel from the 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 buildCopy Anchor Link

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.

pnpm add -D esbuild
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

Native and optional channel dependencies (better-sqlite3, pg, grammy, discord.js, @slack/bolt, playwright, …) stay external.

cogitator daemonCopy Anchor Link

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; -c with a runtime config fails like up -c.

cogitator daemon start [-c <entry>]
cogitator daemon status          # PID, uptime, memory
cogitator daemon logs -f -n 100  # .cogitator/daemon.log (-n defaults to 50)
cogitator daemon restart
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 skillCopy Anchor Link

cogitator skill create weather-api --template api   # -t: basic | device | api; -g for global
cogitator skill validate skills/weather-api         # default: the current directory
cogitator skill list
cogitator skill add ./path/to/skill [-g, --global]
cogitator skill remove weather-api [-g, --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 modelsCopy Anchor Link

cogitator models                       # list installed models
cogitator models --pull qwen2.5:0.5b   # pull with progress
cogitator models --url http://gpu-box:11434

The Ollama URL defaults to OLLAMA_URL, then OLLAMA_HOST, 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 / logsCopy Anchor Link

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

status still reports Ollama when Docker is not running.

cogitator deployCopy Anchor Link

cogitator deploy --dry-run          # analyze + preflight only
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

The plan lists detected services, required secrets (read from the environment or the project's .env), warnings and preflight checks. See @cogitator-ai/deploy for details.

Environment VariablesCopy Anchor Link

See @cogitator-ai/config for every COGITATOR_* variable.