# CLI

URL: https://cogitator.app/docs/cli

> Command-line interface for Cogitator — scaffold assistants, run them as services, chat with agents, manage Ollama models and deploy.

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.

## Installation

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

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

Requires Node.js 22.12+.

## Quick Start

There are two ways to build an assistant:

```bash
# 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:

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

***

## Commands

| Command                  | Description                                                                                  |
| ------------------------ | -------------------------------------------------------------------------------------------- |
| `cogitator init [name]`  | Scaffold a code-first assistant project                                                      |
| `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`](/docs/deployment/deploy-package)) |

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

***

### cogitator init

Creates a TypeScript project with a [`Gateway`](/docs/channels/gateway) wired to your chosen LLM provider, channels and memory adapter.

```bash
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)
```

| Memory choice | Generated adapter | Extra dependency | Notes                               |
| ------------- | ----------------- | ---------------- | ----------------------------------- |
| SQLite        | `SQLiteAdapter`   | `better-sqlite3` | Stored in `./data/memory.db`        |
| In-memory     | `InMemoryAdapter` | —                | Lost on restart                     |
| PostgreSQL    | `PostgresAdapter` | `pg`             | Connection string in `DATABASE_URL` |

`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 wizard

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

```bash
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 / down

```bash
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`](/docs/getting-started/configuration) 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`, …):

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

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

***

### cogitator assistant

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

```bash
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`](https://tsx.is), 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.

```bash
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.json`, `.cogitator.yml`, `.cogitator.yaml`. The file is loaded with [`@cogitator-ai/config`](/docs/getting-started/configuration), 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 build

Bundles a gateway module with [esbuild](https://esbuild.github.io) into a single self-starting ES module. The bundle starts the exported `gateway` and stops it gracefully on `SIGINT`/`SIGTERM`.

```bash
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
```

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

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

***

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

```bash
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 skill

```bash
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 models

```bash
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 / logs

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

| `logs` option        | Default | Description                   |
| -------------------- | ------- | ----------------------------- |
| `[service]`          | all     | Compose service, e.g. `redis` |
| `-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

```bash
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
```

| Option                  | Description                              |
| ----------------------- | ---------------------------------------- |
| `-t, --target <target>` | `docker` (default) or `fly`              |
| `-c, --config <path>`   | Config file with a `deploy:` section     |
| `--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)                   |

The plan lists detected services, required secrets (read from the environment or the project's `.env`), warnings and preflight checks. See [`@cogitator-ai/deploy`](/docs/deployment/deploy-package) 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`, `wizard`, projects from `init` | Provider keys (`init` writes them to `.env`) |
| `COGITATOR_DEBUG`                                       | all                                   | Print stack traces                           |

See [`@cogitator-ai/config`](/docs/getting-started/configuration) for every `COGITATOR_*` variable.