CLI Commands

Overview of the Cognova CLI for managing your self-hosted installation.

The Cognova CLI manages the lifecycle of your installation. All commands operate on the install directory chosen during cognova init.

Command Reference

`cognova init`

Interactive setup wizard. Creates the install directory, generates configuration, sets up the database, installs dependencies, and starts the app with PM2.

cognova init

The wizard steps are covered in detail in Installation.

`cognova start`

Starts the app using the PM2 ecosystem file in the install directory.

cognova start

Requires ecosystem.config.cjs to exist (created by init). If PM2 is not installed, you can start manually:

cd ~/cognova && node .output/server/index.mjs

`cognova stop`

Stops the PM2 process.

cognova stop

`cognova restart`

Restarts the PM2 process. Use after editing .env or other configuration.

cognova restart

`cognova update`

Checks for a newer version on npm, downloads it, updates source files, runs migrations, and restarts.

cognova update

What it does:

Checks npm view cognova version against the installed version
Creates a backup of current source files (.update-backup/)
Downloads and extracts the new package
Copies updated source files (preserves .env, .api-token, node_modules, ecosystem.config.cjs, logs)
Syncs Claude config (skills, hooks, rules) to ~/.claude/
Runs pnpm install and pnpm db:migrate
Restarts the app via PM2

If any step fails, the update automatically rolls back to the backup.

After updating, run cognova reset if you want to regenerate CLAUDE.md or settings.json with any new defaults from the update.

`cognova doctor`

Runs a comprehensive health check across your installation.

cognova doctor

Checks performed:

Check	What it validates
`.env` file	Exists in install directory
`node_modules`	Dependencies installed
Build output	`.output/server/index.mjs` exists
`~/.claude/CLAUDE.md`	Agent identity file
`~/.claude/skills/`	Skills directory
`~/.claude/hooks/`	Hooks directory
`~/.claude/rules/`	Rules directory
`~/.claude/settings.json`	Claude settings
Claude Code CLI	`claude --version` succeeds
Python 3	`python3 --version` succeeds
PM2 process	`cognova` process is online
Health endpoint	`GET /api/health` returns `ok`
Database	Health endpoint reports database available
Vault directory	Path from metadata exists
Version	Matches latest on npm

Each check reports PASS, FAIL, or WARN.

`cognova reset`

Re-generates Claude Code configuration files. Use when you want to update your agent personality or restore config files to defaults.

cognova reset

Presents a multi-select menu:

Option	What it resets
CLAUDE.md	Re-runs personality prompts, regenerates `~/.claude/CLAUDE.md`
Skills	Re-copies skills to `~/.claude/skills/`
Hooks	Re-copies hooks to `~/.claude/hooks/`
Rules	Re-copies rules to `~/.claude/rules/`
Settings	Re-generates `~/.claude/settings.json`

cognova update syncs skills, hooks, and rules automatically. Use reset only for CLAUDE.md/settings regeneration or manual config recovery.

How the CLI Finds Your Installation

The CLI locates your install directory by checking:

A .cognova metadata file in the current working directory
A .cognova metadata file in your home directory (~/.cognova)

The metadata file is written by cognova init and contains the install path, vault path, version, and timestamps.

Deployment Options

Beyond the bare-metal CLI setup, Cognova supports:

Docker Compose -- containerized deployment
Coolify -- one-click deploy with a self-hosted PaaS
Production Checklist -- hardening for remote access

Custom Skills

Step-by-step guide to creating your own Claude Code slash commands, from simple instruction skills to full API-backed Python scripts.

Docker

Deploy Cognova with Docker Compose, including PostgreSQL and Claude Code.