# Command reference
This page documents the shipped command surface, based on `claude-profile --help` and each
subcommand's `--help`.
```
Usage: claude-profile [OPTIONS] [PROFILES]... [-- <EXTRA>...] [COMMAND]
Commands:
list List available profiles and their sources
show Show a profile's details and what it would install
install Install or refresh a profile repo (owner/repo[#ref]) without launching
update Check whether a newer claude-profile release is available, or git-pull profile repos and re-resolve floating marketplaces
status Show each profile's vendored plugins/skills under ~/.claude-profiles/store/
remove Delete a personal profile or cloned pack
new Scaffold a new profile in ~/.claude-profiles/
test Run `claude plugin eval` against a plugin/skill target
try Launch a throwaway session to try a plugin, marketplace, skill, or MCP server
find Search a local index of plugins across marketplaces
self-uninstall Remove the claude-profile binary (and optionally profile data)
completions Print a shell completion script, or write it to the standard location with --install
statusline Install or remove a statusline showing the active profile
coordinate Launch a coordinator session that can delegate tasks to worker sessions
runs List coordinator runs, or remove finished workers' worktrees and finished runs' state
help Print this message or the help of the given subcommand(s)
```
## Progress output
Commands that clone, pull, fetch, or vendor report what they are doing while they work. On a
terminal that is a spinner showing the current unit of work, with a `✓` line for each finished
one. When stderr is not a terminal (piped, redirected, CI) the spinner is suppressed and only the
completion lines are printed, unprefixed.
All of it goes to **stderr** — stdout carries only command results, so `find --json`,
`completions`, `profile-names`, and `statusline-render` stay safe to pipe.
## `claude-profile <profile>... [-- <extra>]`
```
Arguments:
[PROFILES]... Profile name(s) to launch (when no subcommand is given). Give several to launch a combined session; each may be a profile name or a repo reference (owner/repo, URL)
[EXTRA]... Extra args forwarded to claude after `--`
Options:
--yes Skip the provisioning confirmation prompt
```
Launches a session with only the named profile's plugins, skills, and MCP servers enabled.
Running `claude-profile` with no subcommand and no profile prints this help and exits.
Passing **several profiles** launches a combined session enabling the union of them all — e.g.
`claude-profile rust-dev frontend`. Each argument is resolved independently, so any of them may
be a profile name or a repo reference (`owner/repo`, URL). The profiles are merged:
- **plugins** and **pluginDirs**: union (deduped).
- **marketplaces** and **mcpServers**: merged key-by-key. If two profiles define the **same** key
with **different** values, the launch **aborts** and names the conflicting key and profiles
(`marketplace 'm' defined differently by a (o/a) and b (o/b); resolve before combining`);
identical definitions merge cleanly.
- **bare**: must be the same across all selected profiles, else the launch aborts.
A combined launch pins marketplaces into its own lockfile at
`~/.claude-profiles/locks/<a+b>.lock` and sets `CLAUDE_PROFILE=<a+b>`; the individual profiles'
own lockfiles are untouched. A single profile behaves exactly as before.
- **Reads:** the profile JSON (see [profiles.md](profiles.md) for resolution order), its
`<profile>.lock` file if present, and what's already vendored for this profile under
`~/.claude-profiles/store/<profile>/vendor/`.
- **Writes:** on first launch (or whenever new marketplaces/plugins are referenced), clones any
missing marketplaces into `~/.claude-profiles/store/marketplaces/`, copies each referenced
plugin/skill out of the pinned checkout into this profile's own
`~/.claude-profiles/store/<profile>/vendor/`, and writes/updates `<profile>.lock` with the
resolved commit SHA of each marketplace used.
- **Safety behavior:** before vendoring anything new, prints a confirmation prompt showing each
marketplace/plugin's source and pinned ref. `--yes` skips this prompt for scripted use.
Anything after a literal `--` is forwarded to the underlying `claude` invocation unchanged
(e.g. `claude-profile rust-developer -- --continue`).
## `claude-profile <owner/repo>`
Sugar for "install this profile repo, then launch its default profile." Equivalent to running
`claude-profile install <owner/repo>` (which keeps only the repo's profiles, and aborts if it
has none) followed by launching the repo's default profile. Detected by the presence of a `/`
in the argument (as opposed to a bare profile name), so a full `https://…` or `git@…` SSH URL
works here too.
## `show`
```
Usage: claude-profile show <TARGET>
```
Prints a profile's details and exactly what launching it would vendor, without launching or
vendoring anything.
- `<TARGET>` as a bare name: resolves the profile through the normal search path (see
[profiles.md](profiles.md)), expanding `extends` so the plugin/marketplace lists reflect the
full effective set.
- `<TARGET>` as a repo reference (`owner/repo[#ref]`, `https://…`, or `git@…` SSH): shallow-clones
the repo into a **throwaway temp directory**, shows its default profile, then discards the
clone. Nothing is written to `~/.claude-profiles/packs/`.
- **Output:** name, description, author (the profile's `author` field, falling back to the source
repo owner, else `—`), source, then the marketplaces, plugins, MCP servers, and plugin dirs it
declares. A marketplace is marked `(installed)` if its clone already exists under
`~/.claude-profiles/store/marketplaces/`, else `+ … (new)`. A plugin/skill is marked
`(installed)` if it's already vendored into this profile's own
`~/.claude-profiles/store/<profile>/vendor/`, else `+ … (new)` if launching would vendor it.
On a color terminal, installed entries are dimmed and new ones green; output is plain text
when piped or when `NO_COLOR` is set.
## `install`
```
Usage: claude-profile install <SPEC>
```
Installs a profile repo without launching anything. `<SPEC>` is `owner/repo`,
`owner/repo#ref` (tag/branch/SHA), or a full `https://…` / `git@…` SSH git URL (also `#ref`-capable).
- **Behavior:** clones the repo into a temporary directory and keeps **only its profiles** —
a root `profile.json` and everything under `profiles/*.json`. Everything else in the repo
(source, READMEs, the `.git` history) is discarded.
- **Aborts** with a non-zero exit if the repo contains no profiles:
`repo '<spec>' contains no profiles (expected a profile.json or profiles/*.json); nothing to install`.
- **Writes:** the profile files into `~/.claude-profiles/packs/owner--repo/` (the `owner`/`repo`
are taken from the URL path tail), replacing any previous install of the same pack. Because a
pack is stored profiles-only (no `.git`), re-running `install` re-clones fresh rather than
pulling in place, and `update profiles` does not refresh packs — re-run `install` to pick up
changes.
- Does not provision any plugins/marketplaces referenced by the pack's profiles. That
happens the first time one of its profiles is actually launched.
## `update`
```
Usage: claude-profile update [COMMAND]
Commands:
profiles Git-pull profile repos and re-resolve floating marketplaces
```
Checks whether a newer `claude-profile` release is available — it does **not** touch profiles,
packs, or marketplaces (see `update profiles` below for that).
- **Behavior:** compares the running version against the latest GitHub release tag
(`fuzzyalej/claude-profile`). Prints `claude-profile <version> is up to date`, or
`claude-profile <version> is available (you have <version>)` plus an upgrade command guessed
from the running executable's path (`cargo install claude-profiles --force` under
`~/.cargo/bin/`, `brew upgrade claude-profiles` under a Homebrew Cellar, otherwise a link to the
README's install section). Network failures (including "no release published yet") are printed
as a message rather than treated as a hard error.
- **Never replaces the binary itself** — this is a check, not an installer. Re-run whichever
install method you originally used (see [Installing](../README.md#installing)) to actually
upgrade.
## `update profiles`
```
Usage: claude-profile update profiles [OPTIONS]
Options:
--frozen Fail if the lockfile is out of date instead of updating
```
Git-pulls every installed profile repo (pack) and re-resolves floating marketplaces. This is the
command that used to be plain `update` — nothing about its behavior changed, only where it lives
in the CLI.
- **Without `--frozen`:**
1. Pulls every directory under `~/.claude-profiles/packs/` that is still a git checkout,
reporting `updated pack <name>` on stderr for each. Packs installed profiles-only (the current
`install` behavior) have no `.git` and are skipped — re-run `install` to refresh them.
2. For every discoverable profile (same search path as `list`), re-resolves each
**floating** (unpinned/branch-tracking) marketplace to its current HEAD commit and
rewrites that profile's `.lock` file with the new SHA, then re-vendors its plugins from
the new checkout. Marketplaces pinned to an explicit tag/SHA in the profile JSON are left
alone; only floating refs move. A profile whose marketplaces aren't cloned yet is skipped
with a message: launch it once first.
- **With `--frozen`:** does **not** pull packs and does **not** move any marketplace pin.
Instead it re-resolves what each profile's lock *would* need and compares it against what's
currently in `<profile>.lock`. If any profile's lock is stale (missing or out of date for a
marketplace the profile references), the command **fails** and names every stale profile:
`--frozen: lock out of date for profile(s): <name>, <name>, ...`. If every lock is current it
prints `--frozen: all locks up to date` and exits successfully. Use `--frozen` in CI/scripts
to assert "nothing needs updating" without mutating anything.
## `list`
```
Usage: claude-profile list
```
Lists every profile `claude-profile` can find across the full search path (env dir, project
dirs, personal profiles, installed packs, and the engine's own bundled profiles), deduplicated by name
with the highest-priority location winning. Each line is `<name> [<source>]`, where the source
is `env`, `project`, `user`, `pack:<owner--repo>`, or `bundled`. See
[Bundled profiles](profiles.md#bundled-profiles) for the profiles that ship with the binary.
## `status`
```
Usage: claude-profile status
```
Shows, per discoverable profile, what's vendored under
`~/.claude-profiles/store/<profile>/vendor/`: `(not yet provisioned)` if the profile has never
been launched/installed, otherwise the count and list of vendored plugin/skill ids. There is no
shared install to report on — each profile's vendor tree is independent, so nothing here is
ever "unreferenced" by another profile.
## `remove`
```
Usage: claude-profile remove <TARGET>
```
Deletes a profile's data **and** its vendored plugin/skill copies — a real uninstall, not a
disable.
- `<TARGET>` as a bare name (no `/`): deletes that personal/project profile's JSON file, its
`.lock` file if any, and its entire `~/.claude-profiles/store/<name>/vendor/` directory.
- `<TARGET>` as `owner/repo`: deletes the entire cloned pack directory
(`~/.claude-profiles/packs/owner--repo/`).
- **Safety behavior:** refuses to remove one of the engine's own bundled profiles (e.g.
`rust-developer`): those ship with the binary and aren't user data. It also refuses a bare
name that belongs to an installed pack; remove the whole pack with `owner/repo` instead.
- Because each profile's vendored plugins/skills are its own private copies, removing one
profile never affects another's vendor tree, even if both reference the same
`plugin@marketplace` id. There's nothing to prune or garbage-collect afterward.
## `new`
```
Usage: claude-profile new <NAME>
```
Scaffolds a new personal profile.
- **Writes:** creates `~/.claude-profiles/<name>.json` with an empty template (`name`,
`description`, `marketplaces`, `plugins`, `pluginDirs`, `mcpServers` all present but empty)
and prints the path plus a reminder to launch it with `claude-profile <name>` once edited.
- **Safety behavior:** refuses to overwrite an existing file. Fails with `profile '<name>'
already exists at <path>` if one is already there.
- See [profiles.md](profiles.md) for the JSON format to fill in.
## `test`
```
Usage: claude-profile test [OPTIONS] <TARGET> [-- <EXTRA>...]
Options:
--json
```
Runs `claude plugin eval <TARGET>`, a thin wrapper that forwards to Claude Code's own plugin
evaluator so you can test a plugin/skill without hand-writing the `claude` invocation.
- **Behavior:** builds the argv `plugin eval <TARGET> [--json] [EXTRA...]` and executes
`claude` with it, returning `claude`'s own exit code (falls back to `1` if the process didn't
report one).
- `<TARGET>`: the plugin or skill identifier to evaluate, exactly as `claude plugin eval`
expects it.
- `--json`: forwarded to `claude plugin eval --json` for machine-readable output.
- Anything after a literal `--` is forwarded to `claude plugin eval` unchanged (e.g. `claude-profile
test my-skill -- --case "smoke*"`).
## `try`
```
Usage: claude-profile try [OPTIONS] [TARGETS]... [-- <EXTRA>...]
Arguments:
[TARGETS]... What to try. Several targets combine into one temporary profile
[EXTRA]... Extra args forwarded to claude after `--`
Options:
--with <PROFILE> Base the temporary profile on an existing profile. Repeat to combine several
--save <NAME> Keep the generated profile as ~/.claude-profiles/<NAME>.json instead of deleting it
--dry-run Print the generated profile JSON and exit without launching
--command <CMD> Add a stdio MCP server started by this command line
--env <KEY=VAL> Set an environment variable for the MCP servers this command adds. Repeatable
--yes Skip the confirmation prompt
```
Launches a session with a temporary profile built from the targets, so you can test a plugin,
marketplace, skill, or MCP server without writing a profile. When the session ends, the
temporary profile and everything it vendored are deleted.
```sh
claude-profile try npm:@mobilenext/mobile-mcp # an MCP server from npm
claude-profile try obra/superpowers-marketplace # every plugin in a marketplace
claude-profile try superpowers@superpowers-marketplace --with rust-developer
claude-profile try ./my-skill --dry-run # print the profile, don't launch
claude-profile try --command "uvx my-server" --env API_KEY=abc
```
### Targets
Each target is classified by its spelling. The first matching rule wins:
| `npm:<package>` | stdio MCP server: `npx -y <package>@latest`. A version in the package (`npm:foo@1.2`) is kept. |
| `http:<url>` | HTTP MCP server at `<url>`, whatever the host. |
| `https://…` or `http://…` | git repo when the host is `github.com`, `gitlab.com`, `bitbucket.org`, or `codeberg.org`, or the path ends in `.git`. Otherwise an HTTP MCP server. |
| `git@…`, other `scheme://…` | git repo. |
| `.`, `./…`, `../…`, `/…`, `~/…` | local directory. |
| `<plugin>@<marketplace>` | that plugin. The marketplace must be defined by an available profile, listed in the [`find`](#find) index, or tried in the same call. |
| `owner/repo[#ref]` | GitHub repo. |
To reach an MCP endpoint on a git host, use `http:`, for example
`http:https://api.github.com/mcp`.
A git repo is cloned, then checked in this order. A local directory is checked the same way:
1. `profile.json` or `profiles/*.json`: it's a profile repo. `try` stops and tells you to launch
it directly with `claude-profile <repo>`.
2. `.claude-plugin/marketplace.json`: a marketplace. All its plugins load as
`plugin@marketplace`. For a local directory, plugins with relative sources load as plugin
directories.
3. `.claude-plugin/plugin.json`: a plugin. The checkout loads as a plugin directory.
4. `SKILL.md` at the root, or `skills/*/SKILL.md`: skills. They load the same way as vendored
personal skills, with a generated `.claude-plugin/plugin.json`. A local directory is copied
first, so your original stays unchanged.
5. `package.json` with a `bin` field: a stdio MCP server, `npx -y <name>@latest`.
6. Anything else fails. Use `npm:<package>` or `--command` instead.
### Options
- `--with <PROFILE>`: merges the targets on top of an existing profile, the same way a
combined launch merges profiles. Repeat it to combine several. Each value may be a profile
name or a repo reference.
- `--save <NAME>`: writes the generated profile to `~/.claude-profiles/<NAME>.json`, keeps what
it vendored, and launches it. Checkouts that the profile loads as plugin directories are
kept under `~/.claude-profiles/store/<NAME>/repos/`. Fails if `<NAME>.json` already exists.
Can't be combined with `--dry-run`.
- `--dry-run`: prints the generated profile JSON to stdout and exits. Nothing is vendored or
launched. Plugin directories that point into a clone refer to a temporary path that's
already deleted.
- `--command "<cmd …>"`: adds a stdio MCP server started by this command line. Quote arguments
with `'` or `"`. Use it for servers `try` can't detect.
- `--env KEY=VAL`: sets an environment variable on every stdio MCP server that this `try` adds
(`npm:`, detected `package.json`, and `--command`). Servers from `--with` profiles are
unchanged.
- `--yes` and `-- <extra>`: work as they do for a normal launch.
### Behavior
- **Safety behavior:** before it fetches or runs anything, `try` prints every marketplace,
plugin, plugin directory, and MCP server it will load, including each server's full command
line or URL and the names of its environment variables, then asks for confirmation. `--yes`
skips the prompt.
- **Writes:** the temporary profile is named `try-<id>` and lives in
`~/.claude-profiles/tmp/try-<id>/`, so it never shows in `list`. Plugins are vendored into
`~/.claude-profiles/store/try-<id>/` and pinned in `~/.claude-profiles/locks/try-<id>.lock`.
Marketplace and plugin clones that the session adds to `~/.claude-profiles/store/marketplaces/`
are removed with it. Clones that already existed are reused and kept.
- **Cleanup:** `try` waits for `claude` to exit, then deletes everything above, also when
provisioning fails. Ctrl-C goes to `claude`, not to `try`. If `try` itself is killed, the
next `try` run removes what it left behind.
- **Exit code:** `claude`'s own exit code.
## `find`
```
Usage: claude-profile find [OPTIONS] [QUERY]...
Options:
--sync Rebuild the index from seeds (fetches marketplace manifests)
--refresh-seeds Harvest new marketplace seeds before syncing (not yet implemented)
--json Machine-readable output
--limit <N> Maximum number of results (default 20)
--marketplace <NAME> Filter results to a single marketplace
```
Searches a local, offline index of plugins across many marketplaces and prints results as
profile-ready `plugin@marketplace` ids, each with its marketplace's source repo
(`owner/repo`) — copy-paste-ready for a profile's `plugins` and `marketplaces` fields.
- **Behavior:** `<QUERY>` words are matched against each indexed plugin's name, description,
and category (metadata only — it does not search skill file bodies). Matching is
case-insensitive and anchored to word starts: a term matches at the beginning of a word or
after a separator (`-`, `_`, `.`, space), so `rails` finds `ultra-rails-skills` but not
`guardrails`. A term still matches a longer word it begins (`test` finds `testing`).
Multi-word queries are AND: an entry is returned only if every term matches somewhere, and
entries matching more terms, and matching them in the name rather than the description,
rank higher. If no index exists yet, the first run syncs automatically before searching;
every later run
searches the cached index offline unless `--sync` is given. Running `find` with `--sync` or
`--refresh-seeds` and no query just rebuilds the index without searching.
- `--sync`: rebuilds the index now, fetching each seed marketplace's manifest over the
network.
- `--refresh-seeds`: intended to harvest new marketplace seeds before syncing; not yet
implemented — prints a notice and falls back to the existing seed list.
- `--json`: prints the matching entries as a JSON array instead of the human-readable listing.
- `--limit <N>`: caps the number of results (default `20`).
- `--marketplace <NAME>`: restricts results to entries from one marketplace.
- **Seeds:** the index is built from a seed list of marketplace repos — the ~59 marketplaces
bundled with `claude-profile`, plus every marketplace you currently have installed, plus
any repos you add to `~/.claude-profiles/marketplaces.txt` (one `owner/repo` per line, `#`
starts a comment).
- **Reads/writes:** the index is cached at `~/.claude-profiles/.index-cache/index.json`. On a
no-match search, the message includes the index's `generated_at` timestamp so you know how
stale it might be; re-run with `--sync` to refresh it.
## `coordinate`
```
Usage: claude-profile coordinate [OPTIONS] [PROFILES]... [-- <EXTRA>...]
Arguments:
[PROFILES]... Profile name(s) for the coordinator session
[EXTRA]... Extra args forwarded to claude after `--`
Options:
--yes Skip the provisioning confirmation prompt
--max-workers <MAX_WORKERS> Maximum number of workers running at once. Extra spawns queue [default: 4]
--headless Run workers headless even inside Herdr
```
Launches a session like `claude-profile <profile>...`, plus the `claude-profile-workers` MCP
server and a bundled coordinator plugin. The coordinator uses them to start workers, track
them, read their results, and clean up. At least one profile is required, and `--max-workers`
must be at least 1.
- **Workers.** Each worker is a separate session launched as `claude-profile <profiles> --yes
-- <session args> --add-dir <run_dir> <permission flags>`. The server provisions the
worker's profiles before it starts.
- **Mode.** Inside Herdr (`HERDR_ENV=1` and `HERDR_PANE_ID` set), workers open in their own tabs
in the coordinator's workspace. Otherwise they run headless. `--headless` forces headless.
- **System prompt.** `coordinate` appends a delegate-first and clean-up instruction to the
coordinator's system prompt with `--append-system-prompt`. Workers don't get it. Your own
`--append-system-prompt` text is kept and joined with it.
- **Permissions.** Of the arguments after `--`, only `--permission-mode`,
`--dangerously-skip-permissions`, `--allowedTools` (`--allowed-tools`), and
`--disallowedTools` (`--disallowed-tools`) reach workers. Other arguments reach only the
coordinator. When workers run headless and none of these flags is given, `coordinate` prints
a warning, because headless workers can't ask for approval.
- **Writes.** Run state under `~/.claude-profiles/runs/<run-id>/`, worktrees under
`~/.claude-profiles/worktrees/`, and the coordinator plugin under
`~/.claude-profiles/bundled-plugins/`.
See [Coordinate many sessions](coordinate.md) for the full guide.
`workers-mcp` is an internal command. Claude Code starts it from the coordinator's MCP
configuration. Don't run it yourself.
## `runs`
```
Usage: claude-profile runs [OPTIONS] [RUN_ID]
Arguments:
[RUN_ID] Limit --clean to one run
Commands:
wait Block until a worker finishes, fails, or is blocked
Options:
--clean Remove the worktrees, branches, and state of runs that are no longer active
```
Without options, lists coordinator runs, newest first. Each line shows the run ID, the working
directory, and worker counts by status. A run whose `workers-mcp` server is still running ends
with ` (active)`.
With `--clean`, skips active runs and prints `skipped (in use): <run-id>` for each. In every
other run, it treats all workers as finished, removes their worktrees and branches, and then
removes the run. A run ID limits the cleanup to that run. A run ID without `--clean` is an
error.
The `workers-mcp` server holds a lock on `<run_dir>/server.lock` while it runs. A run is
active when that lock is held.
`--clean` never discards work. It keeps a worktree with uncommitted changes and a branch with
commits not merged into the repo's current `HEAD`, and prints one line for each:
```
kept (uncommitted changes): <worktree path>
kept (unmerged branch): cp/<worker-id>
```
A run that has anything kept stays listed.
### `runs wait`
```
Usage: claude-profile runs wait [OPTIONS] [RUN_ID]
Arguments:
[RUN_ID] The run to watch
Options:
--timeout <TIMEOUT> Exit with code 124 after this many seconds without an event
```
Blocks until a worker in the run finishes, fails, or is blocked. It prints one line for each new
event and exits with code 0:
```
<worker-id> done
<worker-id> failed: <reason>
<worker-id> blocked pane <pane_id>
```
Run it with `run_in_background: true` from the coordinator session. Claude Code resumes the
session when the command exits, so the coordinator is notified instead of polling `status`.
Without a run ID, it uses the run whose working directory contains the current directory. Active
runs come first, then the newest. With no match, it exits with an error.
It checks every second:
- **Done or failed.** The worker wrote `result.json`, or its `worker.json` shows a finished status.
- **Failed.** The Herdr pane is gone, or the headless process exited without a result.
- **Blocked.** Herdr reports the agent as blocked. Checked only when the run uses Herdr and
`HERDR_ENV=1`.
Each run keeps a cursor in `<run_dir>/notified.json`, so each event is reported once. Events that
happened before the command started are still reported. A worker that becomes blocked again after
it resumed is reported again, and so is a worker that finishes again after a `send`.
| One or more new events | One line per event | 0 |
| No active workers and nothing new | `no active workers in run <run-id>` | 0 |
| `--timeout` elapsed with no event | `timed out after <n>s with no worker events` | 124 |
The command is read-only toward worker state. It never writes `worker.json`. Only the
`workers-mcp` server updates worker status, so call `status` after the command exits to get the
current state.
## `statusline`
```
Usage: claude-profile statusline <COMMAND>
Commands:
install Install the statusline: shows the active profile in Claude Code's statusline, composed with whatever statusLine command was already configured
uninstall Remove the statusline and restore any prior statusLine config
```
Both subcommands take `--project` to target `./.claude/settings.json` instead of
`~/.claude/settings.json`. See [Statusline](statusline.md).
## `self-uninstall`
```
Usage: claude-profile self-uninstall [OPTIONS]
Options:
--purge Also remove ~/.claude-profiles (all personal profiles, packs, locks)
```
Removes the `claude-profile` binary itself.
- **Writes:** deletes the currently running executable (`std::env::current_exe()`), i.e.
whatever binary you actually invoked.
- `--purge`: additionally removes the entire `~/.claude-profiles` directory — personal
profiles, cloned packs, all `.lock` files, and every profile's vendored plugins/skills under
`store/`. Without `--purge`, profile data (and vendored plugin/skill copies) is left in place.
- **Safety behavior:** never touches `~/.claude`. Since every plugin/skill claude-profile uses
lives in its own vendor tree under `~/.claude-profiles/store/`, `--purge` alone is a complete
uninstall — there is no separate shared-scope cleanup step needed.
See the [top-level README](../README.md#uninstalling) for the full uninstall walkthrough
(including the manual, no-binary-needed path).
## `completions`
```
Usage: claude-profile completions [OPTIONS] <SHELL>
Arguments:
<SHELL> [possible values: bash, zsh, fish, powershell]
Options:
--install Write the script to the standard completion path (and wire it up) instead
of printing it to stdout
```
Prints (or installs) tab-completion for subcommands and, dynamically, for **installed profile
names** — so `claude-profile <TAB>` and `claude-profile show <TAB>` / `remove <TAB>` suggest
whatever `list` would currently show. Profile names are looked up live via the hidden
`profile-names` subcommand (one name per line), so completions always reflect the current
`~/.claude-profiles/` contents — nothing to regenerate after adding or removing a profile.
Without `--install`, the script is printed to stdout so you can pipe or source it yourself, e.g.:
```sh
source <(claude-profile completions zsh) # try it for the current shell session only
```
With `--install`, the script is written to the standard location for that shell and, where the
shell needs it, sourced from its startup file (the edit is idempotent — reinstalling never
duplicates the line):
| `bash` | `~/.claude-profiles/completions/claude-profile.bash` | `~/.bashrc` |
| `zsh` | `~/.claude-profiles/completions/claude-profile.zsh` | `~/.zshrc` |
| `fish` | `~/.config/fish/completions/claude-profile.fish` | none — fish autoloads this dir |
| `powershell` | `~/.claude-profiles/completions/claude-profile.ps1` | `$PROFILE` of each installed PowerShell |
Restart the shell (or source the startup file / run `. $PROFILE` in PowerShell) to pick it up.
For PowerShell, `--install` asks each installed edition (`pwsh` for PowerShell 7 and
`powershell` for Windows PowerShell 5.1) for its `$PROFILE` path, and adds the line to every
profile it finds. That path already accounts for a Documents folder that OneDrive has moved, and
for `pwsh` on macOS and Linux. If neither edition responds, `--install` uses
`Documents/PowerShell/Microsoft.PowerShell_profile.ps1` in your home directory. A new profile
file is saved as UTF-8 with a byte order mark, so Windows PowerShell 5.1 reads non-ASCII user
names in the path correctly.