CLI Reference

Cabinet's CLI is intentionally small. Most of the work happens inside the app, and the CLI exists to start, scaffold, diagnose, and update.

npx cabinetai <command> [args] [flags]

If you've installed Cabinet globally, drop the npx. Everything below uses cabinetai for short.

Commands at a glance

Command	What it does
`create`	Scaffold a new cabinet folder
`run`	Start Cabinet against the current cabinet folder
`list`	List cabinets visible to this install
`add`	Install a template cabinet from cabinets.sh
`doctor`	Diagnose env, ports, providers, db
`sessions`	Manage active sessions and locks
`skills`	Install, update, publish skills
`publish`	Publish the current cabinet to cabinets.sh
`update`	Reinstall the latest version
`uninstall`	Remove cached app (keeps your data)

Global flags

Flag	What it does
`--data-dir <path>`	Override `CABINET_DATA_DIR` for this run.
`--port <n>`	Override the default port (3000).
`--quiet`	Suppress non-error output.
`--json`	Emit machine-readable JSON instead of human output.
`--no-color`	Disable ANSI color in terminal output.
`--help`	Print help for any command.

Environment

Variable	Default	Purpose
`CABINET_DATA_DIR`	`~/cabinets/`	Where Cabinet looks for cabinet folders.
`CABINET_LOG_LEVEL`	`info`	`debug` / `info` / `warn` / `error`.
`CABINET_OFFLINE`	`false`	Skip provider connectivity checks at boot.
`ANTHROPIC_API_KEY`	—	Picked up automatically.
`OPENAI_API_KEY`	—	Picked up automatically.
`GOOGLE_API_KEY`	—	Picked up automatically.
`XAI_API_KEY`	—	Picked up automatically.

Exit codes

Code	Meaning
`0`	Success
`1`	Generic error (see stderr)
`2`	Bad input (missing arg, unknown flag)
`3`	Cabinet not found at the given path
`4`	Port in use
`5`	Provider auth failure
`6`	Schema violation (a malformed persona / job / skill)

`create`

Scaffold a new cabinet folder.

npx cabinetai create [name] [--template <slug>] [--dir <path>] [--no-install]

Arg / flag	Default	What it does
`[name]`	prompts	Folder name. Sluggified for the cabinet id.
`--template <slug>`	empty	Start from a template cabinet on cabinets.sh.
`--dir <path>`	`$CABINET_DATA_DIR`	Parent directory.
`--no-install`	false	Skip `npm install` after scaffold.

Examples

# Empty cabinet, prompts for a name
npx cabinetai create

# Named cabinet
npx cabinetai create my-startup

# From a template
npx cabinetai create my-jobsearch --template cabinet-app/job-hunt-hq

`run`

Start Cabinet against the current folder (or a specified cabinet).

npx cabinetai run [path] [--port <n>] [--open] [--read-only]

Arg / flag	Default	What it does
`[path]`	`.`	Cabinet folder to open.
`--port <n>`	`3000`	Port to bind.
`--open`	true	Open the browser automatically. Use `--no-open` to disable.
`--read-only`	false	Disable agent runs, edits, and git writes. Useful for demos.

Examples

npx cabinetai run                                    # current dir
npx cabinetai run ~/cabinets/my-startup              # specific cabinet
npx cabinetai run --port 3001 --no-open              # alt port, headless
npx cabinetai run --read-only                        # demo mode

`list`

List cabinets visible to this install.

npx cabinetai list [--json]

Reads $CABINET_DATA_DIR for any folder with a .cabinet manifest at the top level.

Output

NAME              ID              KIND     PATH
My Startup        my-startup      root     ~/cabinets/my-startup
Job Hunt HQ       job-hunt-hq     root     ~/cabinets/job-hunt-hq
Acme Client       acme            child    ~/cabinets/agency/clients/acme

`add`

Install a template cabinet from cabinets.sh.

npx cabinetai add <owner/template> [--into <path>] [--name <name>]

Arg / flag	Default	What it does
`<owner/template>`	required	Template slug on cabinets.sh, e.g. `cabinet-app/job-hunt-hq`.
`--into <path>`	`$CABINET_DATA_DIR`	Where to install.
`--name <name>`	template's id	Rename on install.

Heartbeats are paused on first install. Cabinet asks you to confirm each one before it fires.

`doctor`

Diagnose environment, ports, providers, and database integrity.

npx cabinetai doctor [--fix] [--json]

Flag	What it does
`--fix`	Attempt safe auto-fixes (kill stale ports, clear bad locks).
`--json`	Machine-readable output for CI / scripts.

Checks:

Node version ≥ 20
Git installed
$CABINET_DATA_DIR exists and is writable
Default port is free
Each configured provider responds to a ping
The cabinet's SQLite (.cabinet.db) is healthy

`sessions`

Manage active agent sessions and locks.

npx cabinetai sessions list                # show active runs
npx cabinetai sessions kill <id>           # stop a run
npx cabinetai sessions clear-locks         # release stale file locks

`skills`

Install, update, and publish skills.

npx cabinetai skills add <slug> [--global] [--force]
npx cabinetai skills list
npx cabinetai skills update [<slug>]
npx cabinetai skills remove <slug>
npx cabinetai skills publish              # in a skill folder

Use --force only if you've reviewed the security scan output.

`publish`

Publish the current cabinet folder to cabinets.sh.

npx cabinetai publish [--dry-run]

Strips .gitignore'd files, generates a README, validates schemas, and opens a PR to the registry.

`update`

Reinstall the latest Cabinet app version.

npx cabinetai update [--channel <stable|beta>]

Your data is untouched. Only the cached app version changes.

`uninstall`

Remove the cached Cabinet app from your machine.

npx cabinetai uninstall

Your cabinet folders are not affected. They live wherever $CABINET_DATA_DIR points (default ~/cabinets/) and stay where they are.

Read on

Install — the runbook.
File structure — what's inside a cabinet.
Manifest schema — every .cabinet field.