# PAI Command Reference Generated man pages for every `pai` command area. Read any page in the terminal with `pai help `, or browse the files here. ## Areas | Area | Description | |------|-------------| | [`pai audit`](audit.md) | Diagnostic audits: token-waste report and friends | | [`pai backup`](backup.md) | Backup registry, config, and Postgres database to PAI_HOME/backups/ | | [`pai clear-names`](clear-names.md) | Recovery: wipe corrupted iTerm2 session name state. | | [`pai config`](config.md) | PAI_HOME namespace dir: path, migrate | | [`pai daemon`](daemon.md) | PAI daemon management: serve, status, restart, install, uninstall, logs | | [`pai db`](db.md) | Database inspection: query, tables, schema (sqlite or postgres) | | [`pai end`](end.md) | Finalize a session: save state, mark note Completed, display safe-exit instructions. | | [`pai help`](help.md) | Show the man page for a command area (pai help ), or list all areas | | [`pai identity`](identity.md) | Declare who you are: self addresses and where mail is delivered | | [`pai kg`](kg.md) | Temporal knowledge graph: backfill, query, list, stats | | [`pai launch`](launch.md) | Start the Claude Code harness on any provider/model from workers.yaml. | | [`pai mcp`](mcp.md) | MCP server management: install and status | | [`pai memory`](memory.md) | Memory engine: index, search, and status | | [`pai notify`](notify.md) | Notification config: status, get, set, test, send | | [`pai observation`](observation.md) | Observation capture: list, search, and stats | | [`pai obsidian`](obsidian.md) | Obsidian vault: sync project notes, view status, open in Obsidian | | [`pai pause`](pause.md) | Save state and display safe-exit instructions for the current session. | | [`pai project`](project.md) | Alias for `pai projects` | | [`pai projects`](projects.md) | Manage registered projects (list, cd, add, info, ...) | | [`pai registry`](registry.md) | Registry maintenance: scan, migrate, stats, rebuild | | [`pai restore`](restore.md) | Restore from a backup directory (created by pai backup) | | [`pai session`](session.md) | Session management: list, info, checkpoint, handover, cleanup, slug, tag, route. | | [`pai sessions`](sessions.md) | Alias for `pai` — show the unified deduped listing. | | [`pai setup`](setup.md) | Interactive setup wizard — configure storage, embeddings, agent config, and indexing | | [`pai shell-init`](shell-init.md) | Emit shell integration code. Add to ~/.zshrc: eval "$(pai shell-init)" | | [`pai skill`](skill.md) | Skill telemetry and (future) discovery for the self-educating skill system | | [`pai task`](task.md) | Task bus: list, add, dispatch, and complete cross-session work | | [`pai topic`](topic.md) | Topic shift detection: check whether context has drifted to a different project | | [`pai update`](update.md) | Update PAI from GitHub (git pull + rebuild + daemon restart). Preserves local customizations. | | [`pai worker`](worker.md) | Run subagents on configured worker providers: run, ps, follow, replay, | | [`pai zettel`](zettel.md) | Zettelkasten intelligence: explore, surprise, converse, themes, health, suggest | ## All commands | Command | Description | |---------|-------------| | `pai audit` | Diagnostic audits: token-waste report and friends | | `pai audit tokens` | Token-waste audit: memory files, hooks, session usage, spawn overhead, daemon, env, schedule, skill catalogue, subagents, MCP | | `pai audit tokens daemon` | LLM spawns, KG-extraction parse failures, work-queue counts from the daemon log | | `pai audit tokens env` | ANTHROPIC_BASE_URL / model-override env on every live claude process | | `pai audit tokens files [paths...]` | Token count per memory file (CLAUDE.md chain, CORE skill, whisper rules, auto-memory) | | `pai audit tokens hooks` | Token cost of every SessionStart / UserPromptSubmit hook | | `pai audit tokens ladder` | LIVE: first-turn context at increasing headless-worker configuration (spawns real claude -p calls) | | `pai audit tokens mcp` | MCP servers: configured vs. pinned vs. loaded-live vs. used in the last 30 days | | `pai audit tokens schedule` | Launchd agents / crontab entries that outpace the measured prompt-cache TTL | | `pai audit tokens session [path]` | Cache/input/output token split for a session transcript (default: newest) | | `pai audit tokens skills` | Token cost of the SKILL.md / command / plugin catalogue, top entries, duplicate names | | `pai audit tokens spawn` | Spawn-overhead comparison: Agent-tool subagents vs. pai workers | | `pai audit tokens subagents` | Token cost of Claude Code subagent definitions (~/.claude/agents, /.claude/agents) and their model pinning | | `pai backup` | Backup registry, config, and Postgres database to PAI_HOME/backups/ | | `pai clear-names` | Recovery: wipe corrupted iTerm2 session name state. | | `pai config` | PAI_HOME namespace dir: path, migrate | | `pai config get ` | Print one config value (dotted path, e.g. search.recencyBoostDays), masked if it looks like a secret. An object/array subtree prints as YAML; pass --json for JSON. | | `pai config list` | Print the main PAI config as YAML (secrets masked). Defaults to what the file explicitly sets. | | `pai config migrate` | Move config.json, workers.yaml, whisper-rules.md, advisor-mode.json, session-state/, | | `pai config path` | Print the PAI_HOME namespace dir and each resolved per-user file | | `pai config set ` | Set one config value (dotted path). Value parsing: true/false, null, numbers, | | `pai config unset ` | Remove one config value (dotted path), reverting it to the built-in default | | `pai config yaml` | Convert config.json → config.yaml (and voices.json → voices.yaml), with a short | | `pai daemon` | PAI daemon management: serve, status, restart, install, uninstall, logs | | `pai daemon install` | Install daemon as a launchd service and update ~/.claude.json to use the shim | | `pai daemon keepalive` | Show interactive-session cache keepalive config, per-session beat counters, and recent ledger lines | | `pai daemon logs` | Tail the daemon log (/tmp/pai-daemon.log) | | `pai daemon migrate` | Migrate federation data from SQLite to PostgreSQL | | `pai daemon restart` | Send SIGTERM to the running daemon (launchd will restart it) | | `pai daemon serve` | Start the PAI daemon in the foreground | | `pai daemon status` | Query the running daemon status | | `pai daemon uninstall` | Remove the launchd service and revert to direct MCP | | `pai db` | Database inspection: query, tables, schema (sqlite or postgres) | | `pai db query ` | Run a SQL query against the selected database | | `pai db schema ` | Show column schema for a table | | `pai db tables` | List all tables in the selected database | | `pai end` | Finalize a session: save state, mark note Completed, display safe-exit instructions. | | `pai help` | Show the man page for a command area (pai help ), or list all areas | | `pai identity` | Declare who you are: self addresses and where mail is delivered | | `pai identity add ` | Declare an address as your own (widens what can be sent unreviewed) | | `pai identity remove ` | Stop treating an address as your own | | `pai identity set-delivery ` | Set where digests and 'mail me X' are delivered | | `pai identity show` | Show the configured identity | | `pai kg` | Temporal knowledge graph: backfill, query, list, stats | | `pai kg backfill` | Populate the KG from existing session notes (idempotent) | | `pai kg list` | List currently-valid triples | | `pai kg query` | Query KG triples by subject, predicate, object, time, or project | | `pai kg stats` | Show triple counts and contradiction count | | `pai launch` | Start the Claude Code harness on any provider/model from workers.yaml. | | `pai mcp` | MCP server management: install and status | | `pai mcp install` | Register the PAI MCP server (pai) in ~/.claude.json (restart Claude Code to activate) | | `pai mcp status` | Show whether the PAI MCP server (pai) is registered and the binary exists | | `pai memory` | Memory engine: index, search, and status | | `pai memory embed [project-slug]` | Generate embeddings for un-embedded chunks (Phase 2.5) | | `pai memory index [project-slug]` | Index memory files for one project or all projects | | `pai memory search ` | Search indexed memory (BM25 keyword, semantic, or hybrid) | | `pai memory settings [key] [value]` | View or modify search settings in the PAI config file (`pai config path`) | | `pai memory sources` | Show what the indexer has taken in: composition by source, which roots | | `pai memory status [project-slug]` | Show memory index statistics | | `pai notify` | Notification config: status, get, set, test, send | | `pai notify get` | Show current notification config (alias for status) | | `pai notify send ` | Send a notification with an explicit event type and message | | `pai notify set` | Update notification mode or channel configuration | | `pai notify status` | Show current notification mode and active channels | | `pai notify test` | Send a test notification through configured channels | | `pai observation` | Observation capture: list, search, and stats | | `pai observation list` | List recent observations | | `pai observation search ` | Search observations by title or narrative text | | `pai observation stats` | Show observation statistics: totals, by type, by project | | `pai obsidian` | Obsidian vault: sync project notes, view status, open in Obsidian | | `pai obsidian open` | Open the vault in Obsidian (macOS) | | `pai obsidian status` | Show vault health: healthy, broken, orphaned, and missing symlinks | | `pai obsidian sync` | Sync project Notes/ dirs into vault, generate _index.md and topic pages | | `pai pause` | Save state and display safe-exit instructions for the current session. | | `pai project` | Alias for `pai projects` | | `pai project add ` | Register a project directory in the PAI registry | | `pai project alias ` | Register an alternative slug for a project | | `pai project archive ` | Archive a project | | `pai project cd ` | cd to a project directory. Short form: pai cd | | `pai project config [identifier]` | View or modify session launch config for a project. | | `pai project consolidate ` | Consolidate scattered ~/.claude/projects/.../Notes/ directories for a project into its canonical Notes/ location | | `pai project detect [path]` | Detect which registered project the given path (or CWD) belongs to | | `pai project edit ` | Edit project metadata | | `pai project go ` | Print the root path for a project by slug, partial name, or fuzzy match. | | `pai project health` | Audit all registered projects: check which paths still exist, find moved/dead projects | | `pai project here ` | Declare that the CURRENT directory is this project — no slug, no path. | | `pai project info ` | Show full details for a project | | `pai project list` | Show the unified deduped listing (same as `pai`). | | `pai project list-raw` | Raw registry listing with slug, path, status, last_active columns | | `pai project mcp [names...]` | View or set the MCP servers this project's interactive supervisor session | | `pai project merge ` | Fold a duplicate project into another: move its sessions (renumbered), repoint its tags, aliases, compaction records and links, keep the old slug as an alias, then delete the row. Preview unless --execute is given. | | `pai project move ` | Update the root path for a project | | `pai project name ` | Give a project a short name for quick access | | `pai project names` | List named projects (your curated shortlist) | | `pai project promote` | Promote a session note into a new standalone project | | `pai project rebind ` | Manually update the root_path for a project (for when auto-detect found multiple matches). | | `pai project tag ` | Add one or more tags to a project | | `pai project tools [names...]` | View or set the built-in tool schemas this project's interactive | | `pai project unarchive ` | Restore an archived project to active status | | `pai project unname ` | Remove a project's short name | | `pai project unregister ` | Remove a project row entirely, for paths that should never have been registered (worktrees, temp dirs). Refuses when the row holds sessions — merge those first. Preview unless --execute is given. The directory itself is never touched. | | `pai projects` | Manage registered projects (list, cd, add, info, ...) | | `pai projects add ` | Register a project directory in the PAI registry | | `pai projects alias ` | Register an alternative slug for a project | | `pai projects archive ` | Archive a project | | `pai projects cd ` | cd to a project directory. Short form: pai cd | | `pai projects config [identifier]` | View or modify session launch config for a project. | | `pai projects consolidate ` | Consolidate scattered ~/.claude/projects/.../Notes/ directories for a project into its canonical Notes/ location | | `pai projects detect [path]` | Detect which registered project the given path (or CWD) belongs to | | `pai projects edit ` | Edit project metadata | | `pai projects go ` | Print the root path for a project by slug, partial name, or fuzzy match. | | `pai projects health` | Audit all registered projects: check which paths still exist, find moved/dead projects | | `pai projects here ` | Declare that the CURRENT directory is this project — no slug, no path. | | `pai projects info ` | Show full details for a project | | `pai projects list` | Show the unified deduped listing (same as `pai`). | | `pai projects list-raw` | Raw registry listing with slug, path, status, last_active columns | | `pai projects mcp [names...]` | View or set the MCP servers this project's interactive supervisor session | | `pai projects merge ` | Fold a duplicate project into another: move its sessions (renumbered), repoint its tags, aliases, compaction records and links, keep the old slug as an alias, then delete the row. Preview unless --execute is given. | | `pai projects move ` | Update the root path for a project | | `pai projects name ` | Give a project a short name for quick access | | `pai projects names` | List named projects (your curated shortlist) | | `pai projects promote` | Promote a session note into a new standalone project | | `pai projects rebind ` | Manually update the root_path for a project (for when auto-detect found multiple matches). | | `pai projects tag ` | Add one or more tags to a project | | `pai projects tools [names...]` | View or set the built-in tool schemas this project's interactive | | `pai projects unarchive ` | Restore an archived project to active status | | `pai projects unname ` | Remove a project's short name | | `pai projects unregister ` | Remove a project row entirely, for paths that should never have been registered (worktrees, temp dirs). Refuses when the row holds sessions — merge those first. Preview unless --execute is given. The directory itself is never touched. | | `pai registry` | Registry maintenance: scan, migrate, stats, rebuild | | `pai registry dedupe` | Merge registry rows that describe the same project. | | `pai registry lookup` | Find the project slug for a filesystem path (for use in scripts) | | `pai registry migrate` | Import data from ~/.claude/session-registry.json | | `pai registry rebuild` | Erase all registry data and rebuild from the filesystem (destructive) | | `pai registry reconnect` | Point projects back at the transcripts they lost. | | `pai registry scan` | Walk ~/.claude/projects/ and configured scan_dirs, upsert all projects | | `pai registry stats` | Show summary statistics for the registry | | `pai restore` | Restore from a backup directory (created by pai backup) | | `pai session` | Session management: list, info, checkpoint, handover, cleanup, slug, tag, route. | | `pai session active` | Show currently active Claude Code sessions. | | `pai session auto-route` | Auto-detect which project this session belongs to. | | `pai session autosave` | Refresh the ## Continue checkpoint from the transcript and working tree. | | `pai session checkpoint ` | Append a timestamped checkpoint to the active session note. | | `pai session cleanup [project-slug]` | Clean up session notes: delete empties, auto-name unnamed, move into YYYY/MM/ hierarchy, renumber | | `pai session goto ` | Go to a session: resume if a resumable snapshot exists, start fresh otherwise. | | `pai session handover [project-slug] [number-or-latest]` | Write a ## Continue section to the project's TODO.md. | | `pai session info ` | Show full details for a specific session | | `pai session list` | Resumable sessions catalog — named sessions with resume status. | | `pai session pause` | Write a ## Continue checkpoint to the project's TODO.md. | | `pai session recent` | [Deprecated] Use `pai session list` or `pai sessions` instead. | | `pai session rename ` | Rename a session note — updates file on disk, H1 title, and registry | | `pai session restore` | Restore transcripts PAI displaced into sessions/ so claude --resume can find them again. Reports what is unresumable, which checkpoints promise it, and which transcripts are empty. Dry run unless --execute is given. | | `pai session route ` | Create a cross-reference link from a session to a target project | | `pai session slug ` | Generate a descriptive slug from the session JSONL transcript | | `pai session tag [tags...]` | Set or show tags on a session. Tags can be space-separated or comma-separated. | | `pai sessions` | Alias for `pai` — show the unified deduped listing. | | `pai setup` | Interactive setup wizard — configure storage, embeddings, agent config, and indexing | | `pai shell-init` | Emit shell integration code. Add to ~/.zshrc: eval "$(pai shell-init)" | | `pai skill` | Skill telemetry and (future) discovery for the self-educating skill system | | `pai skill telemetry` | Show skill-invocation telemetry (triggers, last used, projects) | | `pai task` | Task bus: list, add, dispatch, and complete cross-session work | | `pai task add