# pai projects > Manage registered projects (list, cd, add, info, ...) ## Synopsis ``` pai projects [options] ``` ## Subcommands | Command | Description | |---------|-------------| | [`pai projects list`](#pai-projects-list) | Show the unified deduped listing (same as `pai`). | | [`pai projects list-raw`](#pai-projects-list-raw) | Raw registry listing with slug, path, status, last_active columns | | [`pai projects cd `](#pai-projects-cd-identifier) | cd to a project directory. Short form: pai cd | | [`pai projects add `](#pai-projects-add-path) | Register a project directory in the PAI registry | | [`pai projects info `](#pai-projects-info-slug) | Show full details for a project | | [`pai projects archive `](#pai-projects-archive-slug) | Archive a project | | [`pai projects merge `](#pai-projects-merge-from-into) | 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 unregister `](#pai-projects-unregister-slug) | 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 unarchive `](#pai-projects-unarchive-slug) | Restore an archived project to active status | | [`pai projects move `](#pai-projects-move-slug-new-path) | Update the root path for a project | | [`pai projects rebind `](#pai-projects-rebind-slug-new-path) | Manually update the root_path for a project (for when auto-detect found multiple matches). | | [`pai projects here `](#pai-projects-here-name) | Declare that the CURRENT directory is this project — no slug, no path. | | [`pai projects tag `](#pai-projects-tag-slug-tags) | Add one or more tags to a project | | [`pai projects alias `](#pai-projects-alias-slug-alias) | Register an alternative slug for a project | | [`pai projects edit `](#pai-projects-edit-slug) | Edit project metadata | | [`pai projects detect [path]`](#pai-projects-detect-path) | Detect which registered project the given path (or CWD) belongs to | | [`pai projects health`](#pai-projects-health) | Audit all registered projects: check which paths still exist, find moved/dead projects | | [`pai projects consolidate `](#pai-projects-consolidate-identifier) | Consolidate scattered ~/.claude/projects/.../Notes/ directories for a project into its canonical Notes/ location | | [`pai projects promote`](#pai-projects-promote) | Promote a session note into a new standalone project | | [`pai projects go `](#pai-projects-go-query) | Print the root path for a project by slug, partial name, or fuzzy match. | | [`pai projects name `](#pai-projects-name-identifier-shortname) | Give a project a short name for quick access | | [`pai projects unname `](#pai-projects-unname-shortname) | Remove a project's short name | | [`pai projects names`](#pai-projects-names) | List named projects (your curated shortlist) | | [`pai projects config [identifier]`](#pai-projects-config-identifier) | View or modify session launch config for a project. | | [`pai projects mcp [names...]`](#pai-projects-mcp-names) | View or set the MCP servers this project's interactive supervisor session | | [`pai projects tools [names...]`](#pai-projects-tools-names) | View or set the built-in tool schemas this project's interactive | ### pai projects list Show the unified deduped listing (same as `pai`). Use --all to include cold / zero-session / archived projects. **Options** | Option | Description | Default | |--------|-------------|---------| | `--all` | Show all entries including cold / zero-session / archived projects | | | `-n, --n ` | Max rows to show | `20` | ### pai projects list-raw Raw registry listing with slug, path, status, last_active columns **Options** | Option | Description | Default | |--------|-------------|---------| | `--all` | Include archived projects (default: active only) | | | `--status ` | Filter by status: active \| archived | | | `--tag ` | Filter by tag | | | `--type ` | Filter by type | | ### pai projects cd cd to a project directory. Short form: pai cd (The shell wrapper handles the actual cd; pure output here.) Auto-detects moved projects when the registered path no longer exists. **Arguments** | Argument | Kind | |----------|------| | `` | required | ### pai projects add Register a project directory in the PAI registry **Arguments** | Argument | Kind | |----------|------| | `` | required | **Options** | Option | Description | Default | |--------|-------------|---------| | `--slug ` | Override auto-generated slug | | | `--type ` | Project type: local \| central \| obsidian-linked \| external | `local` | | `--display-name ` | Human-readable display name | | ### pai projects info Show full details for a project **Arguments** | Argument | Kind | |----------|------| | `` | required | ### pai projects archive Archive a project **Arguments** | Argument | Kind | |----------|------| | `` | required | ### 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. **Arguments** | Argument | Kind | |----------|------| | `` | required | | `` | required | **Options** | Option | Description | Default | |--------|-------------|---------| | `--execute` | Actually perform the merge | | ### 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. **Arguments** | Argument | Kind | |----------|------| | `` | required | **Options** | Option | Description | Default | |--------|-------------|---------| | `--execute` | Actually remove the row | | | `--force` | Remove even though sessions would be deleted with it | | ### pai projects unarchive Restore an archived project to active status **Arguments** | Argument | Kind | |----------|------| | `` | required | ### pai projects move Update the root path for a project **Arguments** | Argument | Kind | |----------|------| | `` | required | | `` | required | ### pai projects rebind Manually update the root_path for a project (for when auto-detect found multiple matches). Validates the new path exists and is a directory, then updates the registry. **Arguments** | Argument | Kind | |----------|------| | `` | required | | `` | required | ### pai projects here Declare that the CURRENT directory is this project — no slug, no path. Repoints an existing project of that name, or creates it. Stores the canonical (realpath) location, so a symlinked parent cannot register the same directory twice. **Arguments** | Argument | Kind | |----------|------| | `` | required | **Options** | Option | Description | Default | |--------|-------------|---------| | `--dry-run` | Show what would change without writing | | ### pai projects tag Add one or more tags to a project **Arguments** | Argument | Kind | |----------|------| | `` | required | | `` | variadic | ### pai projects alias Register an alternative slug for a project **Arguments** | Argument | Kind | |----------|------| | `` | required | | `` | required | ### pai projects edit Edit project metadata **Arguments** | Argument | Kind | |----------|------| | `` | required | **Options** | Option | Description | Default | |--------|-------------|---------| | `--display-name ` | New display name | | | `--type ` | New type | | ### pai projects detect [path] Detect which registered project the given path (or CWD) belongs to **Arguments** | Argument | Kind | |----------|------| | `[path]` | optional | **Options** | Option | Description | Default | |--------|-------------|---------| | `--json` | Output raw JSON instead of human-readable text | | ### pai projects health Audit all registered projects: check which paths still exist, find moved/dead projects **Options** | Option | Description | Default | |--------|-------------|---------| | `--fix` | Auto-remediate where possible | | | `--json` | Output raw JSON report | | | `--status ` | Filter output to: active \| stale \| dead | | ### pai projects consolidate Consolidate scattered ~/.claude/projects/.../Notes/ directories for a project into its canonical Notes/ location **Arguments** | Argument | Kind | |----------|------| | `` | required | **Options** | Option | Description | Default | |--------|-------------|---------| | `--yes` | Perform consolidation without confirmation prompt | | | `--dry-run` | Preview what would be moved without making changes | | ### pai projects promote Promote a session note into a new standalone project **Options** | Option | Description | Default | |--------|-------------|---------| | `--from-session ` | Path to the session note markdown file | | | `--to ` | Directory path for the new project (must not exist) | | | `--name ` | Display name for the new project (derived from filename if omitted) | | ### pai projects go Print the root path for a project by slug, partial name, or fuzzy match. Designed for shell integration: cd $(pai projects go ) **Arguments** | Argument | Kind | |----------|------| | `` | required | ### pai projects name Give a project a short name for quick access **Arguments** | Argument | Kind | |----------|------| | `` | required | | `` | required | **Options** | Option | Description | Default | |--------|-------------|---------| | `--permission ` | Permission level: full \| trusted \| default | | ### pai projects unname Remove a project's short name **Arguments** | Argument | Kind | |----------|------| | `` | required | ### pai projects names List named projects (your curated shortlist) **Options** | Option | Description | Default | |--------|-------------|---------| | `--json` | Output JSON for AIBroker consumption | | | `--all` | Include ALL active registered projects, not just the named shortlist | | ### pai projects config [identifier] View or modify session launch config for a project. Use --options to discover available keys and presets. **Arguments** | Argument | Kind | |----------|------| | `[identifier]` | optional | **Options** | Option | Description | Default | |--------|-------------|---------| | `--set ` | Set config values (repeatable) | `` | | `--unset ` | Remove config keys (repeatable, use env.KEY for env vars) | `` | | `--preset ` | Apply a permission preset: full \| trusted \| default | | | `--defaults` | Manage global session defaults instead of a project | | | `--options` | List available config keys and presets | | | `--json` | Output JSON | | | `--reset` | Reset config to empty (inherit global defaults) | | ### pai projects mcp [names...] View or set the MCP servers this project's interactive supervisor session loads (run from inside the project, like `pai projects here`). No names: print the current value. Names (comma-separated or repeated args): set it, validated against ~/.claude.json's mcpServers. --clear: unset (all servers load — today's default). **Arguments** | Argument | Kind | |----------|------| | `[names...]` | variadic | **Options** | Option | Description | Default | |--------|-------------|---------| | `--clear` | Unset — all MCP servers load again | | ### pai projects tools [names...] View or set the built-in tool schemas this project's interactive supervisor session loads (run from inside the project, like `pai projects here`). No names: print the current value. Names (comma-separated or repeated args): set it. --clear: unset (all tools load — today's default). **Arguments** | Argument | Kind | |----------|------| | `[names...]` | variadic | **Options** | Option | Description | Default | |--------|-------------|---------| | `--clear` | Unset — all built-in tools load again | | ## Examples ```bash # Jump into a project directory (with the shell wrapper installed) pai cd pai # Register the current directory as a project pai projects add . # Show everything known about a project pai projects info pai # Repair a project whose folder moved on disk pai projects rebind pai /new/path/to/pai # Audit all registered projects for dead / moved paths pai projects health --fix ``` ## See also [`pai audit`](audit.md) · [`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai config`](config.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai identity`](identity.md) · [`pai kg`](kg.md) · [`pai launch`](launch.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai session`](session.md) · [`pai sessions`](sessions.md) · [`pai setup`](setup.md) · [`pai shell-init`](shell-init.md) · [`pai skill`](skill.md) · [`pai task`](task.md) · [`pai topic`](topic.md) · [`pai update`](update.md) · [`pai worker`](worker.md) · [`pai zettel`](zettel.md) Run `pai help ` to read any of these in the terminal.