@bordoni/claudep 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,29 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-14
+
+### Added
+
+- `claudep completion zsh|bash|fish` prints tab completions for every subcommand, its flags, the values `--shell`, `shell-init` and `completion` take, and your profile names. Load it with `eval "$(claudep completion zsh)"` after `compinit`, `eval "$(claudep completion bash)"`, or `claudep completion fish | source`. Profile names are read from `~/.claudep` when you press Tab, so the script never runs claudep.
+
+### Changed
+
+- **Breaking:** `completion` is now a reserved word. A profile named `completion` stops resolving; recreate it under another name. Reserved words, flag parsing and the completion scripts now come from one command table, so they cannot drift apart.
+
+## [0.3.0] - 2026-09-10
+
+### Added
+
+- fish support: `claudep shell-init fish` prints a hook for `config.fish` that follows `.claudep` pins on `cd` using builtins only, and `claudep env` prints `set -gx` and `set -e` lines when run from fish. Load both with `| source`. Needs fish 3.0 or later.
+- `claudep env` looks at the shell it runs in (fish, pwsh, or an sh-like shell) before falling back to `$SHELL`, and `--shell sh|zsh|bash|fish|powershell` overrides both. `claudep env <name> | Invoke-Expression` works in pwsh on macOS and Linux as a result.
+- `claudep current --name` prints only the profile name (`default` for `~/.claude`, `custom` for a config dir outside the profiles root), for prompts, scripts and the statusline.
+- `claudep list --json` prints the same flat objects as `claudep status --json`, one per profile.
+- `claudep doctor` fails when the shared `settings.json` sets `env.CLAUDE_CONFIG_DIR`, and on macOS when Claude Code is older than 2.1.144, the first build whose Keychain item is namespaced per config dir.
+- `claudep doctor` and `claudep <name>` warn when `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` or `CLAUDE_CODE_OAUTH_TOKEN` is set, because Claude Code uses it instead of the profile's login. The variable is left alone.
+- `claudep rm` says when the shell is on the profile being removed or the current directory pins it, and names the command that clears each.
+- CI runs the shell hook in fish on macOS and Linux.
+
 ## [0.2.1] - 2026-09-08
 
 ### Changed
@@ -63,7 +86,9 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 - Keychain isolation per config dir verified against Claude Code 2.1.259: the service name is `Claude Code-credentials-<sha256(dir)[0:8]>`.
 - Test suite with `bun test`, a sandboxed `$HOME`, a fake `claude` and `security` on PATH, and a real-shell test for the hook. CI runs typecheck, lint and tests on macOS and Linux.
 
-[Unreleased]: https://github.com/bordoni/claudep/compare/0.2.1...HEAD
+[Unreleased]: https://github.com/bordoni/claudep/compare/0.4.0...HEAD
+[0.4.0]: https://github.com/bordoni/claudep/compare/0.3.0...0.4.0
+[0.3.0]: https://github.com/bordoni/claudep/compare/0.2.1...0.3.0
 [0.2.1]: https://github.com/bordoni/claudep/compare/0.2.0...0.2.1
 [0.2.0]: https://github.com/bordoni/claudep/compare/0.1.1...0.2.0
 [0.1.1]: https://github.com/bordoni/claudep/compare/0.1.0...0.1.1

package/README.md

@@ -54,16 +54,17 @@ Two things differ from macOS:
 ```
 claudep <name> [claude args…]        run claude with profile <name>
 claudep init <name> [options]        create/update a profile and log in
-claudep list                         every profile and who it is logged in as
+claudep list [--json]                every profile and who it is logged in as
 claudep status <name> [--json]       login state for one profile ("default" = ~/.claude)
-claudep env <name>                   print "export CLAUDE_CONFIG_DIR=…" for eval
+claudep env <name> [--shell <sh>]    print the CLAUDE_CONFIG_DIR pin for eval, source or Invoke-Expression
 claudep alias <name> <command>       write a shim so "<command>" == "claudep <name>"
-claudep current [--json]             which profile this shell is on, and why
-claudep doctor [name]                verify symlinks, keychain entry, unclassified files
+claudep current [--json|--name]      which profile this shell is on, and why
+claudep doctor [name]                verify symlinks, keychain entry, unclassified files, Claude Code version
 claudep rm <name> [--keep-login]     log out and delete a profile (base is never touched)
 claudep local <name> | --remove      pin the current directory tree to a profile (see below)
 claudep resolve [dir]                print the profile pinned for a directory
-claudep shell-init [zsh|bash|powershell]   print the hook that applies pins on cd
+claudep shell-init [zsh|bash|fish|powershell]   print the hook that applies pins on cd
+claudep completion [zsh|bash|fish]   print tab completions for commands, flags and profile names
 claudep --version
 ```
 
@@ -84,20 +85,57 @@ Shells apply pins through a hook. Add one line to `~/.zshrc` (or `~/.bashrc` wit
 eval "$(claudep shell-init zsh)"
 ```
 
-In PowerShell the line goes in `$PROFILE`:
+In fish the line goes in `~/.config/fish/config.fish`, and in PowerShell in `$PROFILE`:
+
+```fish
+claudep shell-init fish | source
+```
 
 ```powershell
 claudep shell-init powershell | Out-String | Invoke-Expression
 ```
 
-From then on, `cd` into a pinned tree sets `CLAUDE_CONFIG_DIR` for that profile and `cd` out of it returns the shell to `~/.claude`. The hook is pure shell with no subprocess (cmdlets only in PowerShell), so it costs nothing at the prompt. The rules:
+From then on, `cd` into a pinned tree sets `CLAUDE_CONFIG_DIR` for that profile and `cd` out of it returns the shell to `~/.claude`. The hook is pure shell with no subprocess (builtins in fish, cmdlets only in PowerShell), so it costs nothing at the prompt. The rules:
 
 - The nearest `.claudep` file upward from the current directory wins. An empty one cancels a parent pin.
-- The hook only changes a `CLAUDE_CONFIG_DIR` it set itself. It tracks that in `CLAUDEP_AUTO`, so a manual pin from `eval "$(claudep env work)"` (`claudep env work | Invoke-Expression` in PowerShell) or a plain `export` stays put until you `eval "$(claudep env --unset)"`.
+- The hook only changes a `CLAUDE_CONFIG_DIR` it set itself. It tracks that in `CLAUDEP_AUTO`, so a manual pin from `eval "$(claudep env work)"` (`claudep env work | source` in fish, `claudep env work | Invoke-Expression` in PowerShell) or a plain `export` stays put until you `eval "$(claudep env --unset)"`.
 - A pin that names a profile you have not created prints one warning per directory change and sets nothing.
 
+`claudep env` prints the syntax of the shell it runs in: it looks at its parent process (fish, pwsh, or an sh-like shell) and falls back to your login shell. Pass `--shell sh|fish|powershell` when neither answer fits, for example from a script or a Makefile.
+
 `claudep current` tells you which profile the shell is on and how it got there (hook, manual pin, or nothing). `claudep list` adds the same line at the bottom.
 
+## Tab completion
+
+One line in your rc file completes subcommands, their flags, the values `--shell` and `shell-init` take, and your profile names:
+
+```sh
+eval "$(claudep completion zsh)"      # ~/.zshrc, after compinit
+eval "$(claudep completion bash)"     # ~/.bashrc
+```
+
+```fish
+claudep completion fish | source      # ~/.config/fish/config.fish
+```
+
+Profile names come from a directory listing of `~/.claudep` at the moment you press Tab, so the script never runs claudep and a new profile shows up without reloading anything. In zsh the same output also works as a file: `claudep completion zsh > ~/.zfunc/_claudep` with `~/.zfunc` on `fpath` before `compinit`, if you prefer autoloading over `eval`.
+
+## Show the profile in your prompt or statusline
+
+In a shell prompt use the variable itself; no command runs:
+
+```sh
+# zsh or bash: the last path segment is the profile name when a profile is active
+PROMPT='${CLAUDE_CONFIG_DIR:+[${CLAUDE_CONFIG_DIR##*/}] }'"$PROMPT"
+```
+
+```fish
+# fish
+function fish_prompt; set -q CLAUDE_CONFIG_DIR; and echo -n "[$(string replace -r '.*/' '' -- $CLAUDE_CONFIG_DIR)] "; ...; end
+```
+
+In scripts, and in the shared `statusline-command.sh`, `claudep current --name` prints exactly one word: the profile name, `default` for `~/.claude`, or `custom` for a `CLAUDE_CONFIG_DIR` outside the profiles root. The statusline script inherits Claude Code's environment, so it sees the profile the session was started with.
+
 ## How it works
 
 `~/.claude` is left exactly as it is and stays the **default** profile. Each named profile is a thin directory under `~/.claudep/<name>`. Inside it, shared configuration is a symlink back into `~/.claude`:
@@ -119,7 +157,9 @@ The shared list is an allowlist, so an account-specific file cannot leak across
 - Two profiles running at the same time write the same `settings.json` and `plugins/`. That is the same situation as two terminals today.
 - Background sessions and the daemon are tied to `~/.claude`. As of Claude Code 2.1.263, `claude daemon install` refuses to run with `CLAUDE_CONFIG_DIR` set, and `claude --bg` under a profile runs without the daemon.
 - Set `CLAUDE_PROFILES_DIR` to move the profiles root. Keep it out of iCloud or Dropbox; `.claude.json` is rewritten constantly and sync tools create conflict copies.
-- Never put `CLAUDE_CONFIG_DIR` in a `settings.json` `env` block. Claude Code detects that mismatch and disables features.
+- Never put `CLAUDE_CONFIG_DIR` in a `settings.json` `env` block. Claude Code detects that mismatch and disables features; `claudep doctor` reports it.
+- `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` and `CLAUDE_CODE_OAUTH_TOKEN` override the login in any config dir, always in `-p` mode. `claudep <name>` and `claudep doctor` warn when one is set and leave it alone.
+- `claudep doctor` fails on macOS when Claude Code is older than 2.1.144, the first build whose Keychain item is namespaced per config dir.
 
 ## Releases
 

package/claudep.ts

@@ -317,27 +317,87 @@ export const SEED_KEYS = [
 ] as const;
 
 export const NAME_RE = /^[a-z0-9][a-z0-9_-]*$/;
+
+/** Shells with a directory-pin hook, and the subset with tab completions. */
+export type Shell = "zsh" | "bash" | "fish" | "powershell";
+export const SHELLS: readonly Shell[] = ["zsh", "bash", "fish", "powershell"];
+export const COMPLETION_SHELLS = ["zsh", "bash", "fish"] as const;
+export type CompletionShell = (typeof COMPLETION_SHELLS)[number];
+/** What `claudep env --shell` accepts. */
+export const ENV_SHELLS = ["sh", "zsh", "bash", "fish", "powershell"] as const;
+
+export type ValueFlag = { name: string; values?: readonly string[] };
+export type Command = {
+  name: string;
+  /** One line, no colons: it becomes the zsh _describe and fish -d text. */
+  desc: string;
+  aliases?: readonly string[];
+  /** What the first positional completes to. */
+  arg?: "profile" | "dir" | readonly string[];
+  flags?: readonly string[];
+  valueFlags?: readonly ValueFlag[];
+  /** A real command that the top-level completion does not offer. */
+  hidden?: boolean;
+};
+
+/** One table for the dispatcher's reserved words, every parseFlags call and
+ *  the completion scripts, so none of them can drift from the others. */
+export const COMMANDS: readonly Command[] = [
+  {
+    name: "init",
+    desc: "create or update a profile and log in",
+    arg: "profile",
+    flags: ["--sso", "--console", "--copy-mcp", "--no-login", "--force"],
+    valueFlags: [{ name: "--email" }, { name: "--alias" }],
+  },
+  { name: "run", desc: "run claude with a profile", arg: "profile", hidden: true },
+  { name: "list", desc: "show every profile and who it is logged in as", aliases: ["ls"], flags: ["--json"] },
+  { name: "status", desc: "login state for one profile", arg: "profile", flags: ["--json"] },
+  { name: "current", desc: "which profile this shell is on, and why", flags: ["--json", "--name"] },
+  {
+    name: "env",
+    desc: "print the CLAUDE_CONFIG_DIR pin, or the unset, for your shell",
+    arg: "profile",
+    flags: ["--unset"],
+    valueFlags: [{ name: "--shell", values: ENV_SHELLS }],
+  },
+  { name: "alias", desc: "write a shim command that runs claudep with a profile", arg: "profile" },
+  { name: "doctor", desc: "verify symlinks, keychain entry, unclassified files, Claude Code version", arg: "profile" },
+  {
+    name: "rm",
+    desc: "log out and delete a profile",
+    aliases: ["remove"],
+    arg: "profile",
+    flags: ["--keep-login", "--yes"],
+  },
+  { name: "local", desc: "pin this directory tree to a profile", arg: "profile", flags: ["--remove", "--force"] },
+  { name: "resolve", desc: "print the profile pinned for a directory", arg: "dir", flags: ["--json"] },
+  { name: "shell-init", desc: "print the hook that applies pins on cd", arg: SHELLS },
+  { name: "completion", desc: "print tab completions for a shell", arg: COMPLETION_SHELLS },
+  { name: "help", desc: "show the help" },
+  { name: "version", desc: "print the version", aliases: ["--version"] },
+];
+
+/** The words a completion offers for a command: its name and the aliases
+ *  that are words (a `--version` alias is a flag, not a word). */
+export function commandWords(c: Command): string[] {
+  return [c.name, ...(c.aliases ?? [])].filter((w) => !w.startsWith("-"));
+}
+
+/** Profile names that would collide with the dispatcher. Derived from the
+ *  table plus the two names for the base. */
 export const RESERVED = new Set([
   "default",
   "base",
-  "init",
-  "run",
-  "list",
-  "ls",
-  "status",
-  "env",
-  "doctor",
-  "rm",
-  "remove",
-  "alias",
-  "help",
-  "current",
-  "local",
-  "resolve",
-  "shell-init",
-  "version",
+  ...COMMANDS.flatMap((c) => [c.name, ...(c.aliases ?? [])]).filter((w) => NAME_RE.test(w)),
 ]);
 
+/** The boolean and value flag names a command accepts, for parseFlags. */
+export function flagSpec(name: string): [readonly string[], readonly string[]] {
+  const c = COMMANDS.find((x) => x.name === name);
+  return [c?.flags ?? [], (c?.valueFlags ?? []).map((v) => v.name)];
+}
+
 // ---------------------------------------------------------------------------
 // Output helpers
 // ---------------------------------------------------------------------------
@@ -521,6 +581,49 @@ export async function readJson(path: string): Promise<JsonObject | undefined> {
   }
 }
 
+/** Variables Claude Code uses instead of the login in its config dir when
+ *  they are set (always in -p mode). They make a profile's login moot. */
+export const AUTH_ENV = ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN"] as const;
+
+/** The AUTH_ENV names that are set and non-empty. Windows environments are
+ *  case-insensitive, so any spelling counts there. */
+export function authEnvOverrides(env: Env = process.env, platform: NodeJS.Platform = process.platform): string[] {
+  return AUTH_ENV.filter((name) => {
+    if (platform !== "win32") return Boolean(env[name]);
+    return Object.keys(env).some((k) => k.toUpperCase() === name && Boolean(env[k]));
+  });
+}
+
+/** The oldest Claude Code whose macOS Keychain item is namespaced per config
+ *  dir. Before it every config dir shared one login. */
+export const MIN_CLAUDE_VERSION = "2.1.144";
+
+export type Version = [number, number, number];
+
+/** The first x.y.z in `claude --version` output. */
+export function parseVersion(text: string): Version | undefined {
+  const m = /(\d+)\.(\d+)\.(\d+)/.exec(text);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : undefined;
+}
+
+export function versionBelow(a: Version, b: Version): boolean {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return (a[i] as number) < (b[i] as number);
+  }
+  return false;
+}
+
+/** `env.CLAUDE_CONFIG_DIR` from a settings file, when present and a string.
+ *  Claude Code disables features when it finds one that differs from the
+ *  active dir, and under claudep it always differs for some profile. */
+export async function settingsEnvConfigDir(settingsPath: string): Promise<string | undefined> {
+  const settings = await readJson(settingsPath);
+  const env = settings?.env;
+  if (!env || typeof env !== "object" || Array.isArray(env)) return undefined;
+  const value = (env as JsonObject).CLAUDE_CONFIG_DIR;
+  return typeof value === "string" ? value : undefined;
+}
+
 export type SeedResult = "seeded" | "exists" | "no-base";
 
 export async function seedGlobalJson(baseGlobalJson: string, dir: string, copyMcp: boolean): Promise<SeedResult> {
@@ -774,7 +877,7 @@ export function parseFlags(args: string[], boolNames: readonly string[], strName
 // ---------------------------------------------------------------------------
 
 async function cmdInit(L: Layout, args: string[]): Promise<void> {
-  const f = parseFlags(args, ["--copy-mcp", "--no-login", "--sso", "--console", "--force"], ["--email", "--alias"]);
+  const f = parseFlags(args, ...flagSpec("init"));
   const name = f.rest[0];
   if (!name)
     die(
@@ -915,6 +1018,8 @@ async function cmdRun(L: Layout, args: string[]): Promise<never> {
   if (name === "default" || name === "base") return execClaude(L, undefined, rest);
   const dir = profileDir(L, name);
   if (!existsSync(dir)) die(`profile "${name}" does not exist. Run: claudep init ${name}`);
+  for (const v of authEnvOverrides(process.env, L.platform))
+    console.error(`claudep: ${v} is set; Claude Code will use it instead of the "${name}" login`);
   return execClaude(L, dir, rest);
 }
 
@@ -952,58 +1057,91 @@ function printTable(rows: Row[], home: string, platform: NodeJS.Platform): void
   });
 }
 
-async function cmdList(L: Layout): Promise<void> {
+/** The flat object `status --json` prints for one row; `list --json` prints an array of them. */
+function rowJson(row: Row): JsonObject {
+  return { name: row.name, dir: row.dir, ...row.status };
+}
+
+async function cmdList(L: Layout, args: string[]): Promise<void> {
+  const f = parseFlags(args, ...flagSpec("list"));
   const names = ["default", ...listProfileNames(L)];
-  printTable(await collectRows(L, names), L.home, L.platform);
+  const rows = await collectRows(L, names);
+  if (f.bools.has("--json")) {
+    console.log(JSON.stringify(rows.map(rowJson), null, 2));
+    return;
+  }
+  printTable(rows, L.home, L.platform);
   if (names.length === 1) console.log(c.dim("\nNo profiles yet. Create one: claudep init <name>"));
   const cur = currentProfile(L);
   if (cur.kind !== "base") console.log(c.dim(`\nactive in this shell: ${describeCurrent(cur)}`));
 }
 
 async function cmdStatus(L: Layout, args: string[]): Promise<void> {
-  const f = parseFlags(args, ["--json"], []);
+  const f = parseFlags(args, ...flagSpec("status"));
   const name = f.rest[0];
   if (!name) die("usage: claudep status <name> [--json]");
   if (name !== "default" && !profileExists(L, name)) die(`profile "${name}" does not exist`);
   const [row] = await collectRows(L, [name]);
   if (!row) return;
-  if (f.bools.has("--json")) console.log(JSON.stringify({ name: row.name, dir: row.dir, ...row.status }, null, 2));
+  if (f.bools.has("--json")) console.log(JSON.stringify(rowJson(row), null, 2));
   else printTable([row], L.home, L.platform);
 }
 
+function envUsage(syntax: EnvSyntax): string {
+  if (syntax === "powershell")
+    return "usage: claudep env <name> | Invoke-Expression   or   claudep env --unset | Invoke-Expression";
+  if (syntax === "fish") return "usage: claudep env <name> | source   or   claudep env --unset | source";
+  return 'usage: eval "$(claudep env <name>)"   or   eval "$(claudep env --unset)"   (add --shell fish|powershell|sh when the shell was not detected)';
+}
+
+/** The line that clears a pin, in the syntax of the shell the user is in. */
+export function envUnsetHint(syntax: EnvSyntax): string {
+  if (syntax === "powershell") return "claudep env --unset | Invoke-Expression";
+  if (syntax === "fish") return "claudep env --unset | source";
+  return 'eval "$(claudep env --unset)"';
+}
+
 function cmdEnv(L: Layout, args: string[]): void {
-  const name = args[0];
-  const syntax = shellSyntax(process.env, L.platform);
-  if (!name)
-    die(
-      syntax === "powershell"
-        ? "usage: claudep env <name> | Invoke-Expression   or   claudep env --unset | Invoke-Expression"
-        : 'usage: eval "$(claudep env <name>)"   or   eval "$(claudep env --unset)"',
-    );
-  if (name === "--unset") {
+  const f = parseFlags(args, ...flagSpec("env"));
+  const forced = f.strs.get("--shell");
+  const syntax =
+    forced === undefined ? shellSyntax(process.env, L.platform, parentProcessName(L.platform)) : envSyntaxOf(forced);
+  if (!syntax) die(`unsupported shell "${forced}". Use sh, zsh, bash, fish or powershell`);
+  if (f.bools.has("--unset")) {
     process.stdout.write(envScript(undefined, syntax));
     return;
   }
+  const name = f.rest[0];
+  if (!name) die(envUsage(syntax));
   const dir = profileDir(L, name);
   if (!existsSync(dir)) die(`profile "${name}" does not exist`);
   process.stdout.write(envScript(dir, syntax));
 }
 
 function describeCurrent(cur: Current): string {
-  const label = cur.kind === "profile" ? (cur.name ?? "?") : cur.kind === "custom" ? "custom" : "default";
+  const label = currentLabel(cur);
   const how = cur.setBy === "hook" ? "shell hook" : cur.setBy === "manual" ? "manual pin" : "nothing pinned";
   return `${label} (${how})`;
 }
 
+/** The one-word answer: the profile name, `default` for the base, `custom` otherwise. */
+export function currentLabel(cur: Current): string {
+  return cur.kind === "profile" ? (cur.name ?? "?") : cur.kind === "custom" ? "custom" : "default";
+}
+
 function cmdCurrent(L: Layout, args: string[]): void {
-  const f = parseFlags(args, ["--json"], []);
+  const f = parseFlags(args, ...flagSpec("current"));
   const cur = currentProfile(L);
+  const label = currentLabel(cur);
+  if (f.bools.has("--name")) {
+    console.log(label);
+    return;
+  }
   const pin = resolvePin(process.cwd());
   if (f.bools.has("--json")) {
     console.log(JSON.stringify({ ...cur, pin: pin ?? null }, null, 2));
     return;
   }
-  const label = cur.kind === "profile" ? (cur.name ?? "?") : cur.kind === "custom" ? "custom" : "default";
   console.log(`${c.bold(label)}  ${c.dim(shortHome(cur.dir, L.home, L.platform))}`);
   if (cur.setBy === "hook")
     console.log(`set by: shell hook${pin ? ` (${PIN_FILE} in ${shortHome(pin.dir, L.home, L.platform)})` : ""}`);
@@ -1022,7 +1160,7 @@ function cmdCurrent(L: Layout, args: string[]): void {
 }
 
 function cmdResolve(L: Layout, args: string[]): void {
-  const f = parseFlags(args, ["--json"], []);
+  const f = parseFlags(args, ...flagSpec("resolve"));
   const start = f.rest[0] ?? process.cwd();
   const pin = resolvePin(start);
   if (!pin || pin.name === "") process.exit(1);
@@ -1033,7 +1171,7 @@ function cmdResolve(L: Layout, args: string[]): void {
 }
 
 function cmdLocal(L: Layout, args: string[]): void {
-  const f = parseFlags(args, ["--remove", "--force"], []);
+  const f = parseFlags(args, ...flagSpec("local"));
   const file = join(process.cwd(), PIN_FILE);
   if (f.bools.has("--remove")) {
     if (!existsSync(file)) die(`no ${PIN_FILE} in ${process.cwd()}`);
@@ -1062,29 +1200,83 @@ function cmdLocal(L: Layout, args: string[]): void {
 
 /** The shell hook. Pure parameter expansion and builtins: it runs on every
  *  directory change (zsh chpwd) or prompt (bash PROMPT_COMMAND), so no
- *  subprocess is allowed here. Logic mirrors resolvePin(). */
-export type Shell = "zsh" | "bash" | "powershell";
-export const SHELLS: readonly Shell[] = ["zsh", "bash", "powershell"];
+ *  subprocess is allowed here. Logic mirrors resolvePin(). `Shell` and
+ *  `SHELLS` live next to the command table. */
 
 /** The shell to name in hints and to default `shell-init` to. */
 export function defaultShell(env: Env = process.env, platform: NodeJS.Platform = process.platform): Shell {
   if (platform === "win32") return env.MSYSTEM ? "bash" : "powershell";
   const name = env.SHELL ? posix.basename(env.SHELL) : "";
-  if (name === "zsh" || name === "bash") return name;
+  if (name === "zsh" || name === "bash" || name === "fish") return name;
   return platform === "darwin" ? "zsh" : "bash";
 }
 
 /** The one line that loads the hook in a shell's rc file. */
 export function hookHint(shell: Shell): string {
   if (shell === "powershell") return "claudep shell-init powershell | Out-String | Invoke-Expression";
+  if (shell === "fish") return "claudep shell-init fish | source";
   return `eval "$(claudep shell-init ${shell})"`;
 }
 
-export type EnvSyntax = "sh" | "powershell";
+export type EnvSyntax = "sh" | "fish" | "powershell";
 
-/** What `claudep env` prints. PowerShell syntax only on Windows outside Git Bash. */
-export function shellSyntax(env: Env = process.env, platform: NodeJS.Platform = process.platform): EnvSyntax {
-  return platform === "win32" && !env.MSYSTEM ? "powershell" : "sh";
+/** The executable name of the parent process, which for `claudep env` is
+ *  the shell the user typed it in: `eval "$(...)"` forks the shell and a
+ *  fish pipeline runs claudep as a child of fish. Read from /proc on Linux
+ *  and from `ps` on macOS; undefined elsewhere or when it cannot be read.
+ *  This is `claudep env`, not the hook, so one `ps` is fine. */
+export function parentProcessName(
+  platform: NodeJS.Platform = process.platform,
+  ppid: number = process.ppid,
+): string | undefined {
+  try {
+    if (platform === "linux") return readFileSync(`/proc/${ppid}/comm`, "utf8").trim() || undefined;
+    if (platform === "darwin") {
+      const r = Bun.spawnSync(["ps", "-o", "comm=", "-p", String(ppid)], { stdout: "pipe", stderr: "ignore" });
+      const name = r.exitCode === 0 ? r.stdout.toString().trim() : "";
+      return name || undefined;
+    }
+  } catch {
+    /* fall through */
+  }
+  return undefined;
+}
+
+/** `fish` from `fish`, `-fish` (a login shell) or `/usr/local/bin/fish`. */
+export function shellNameOf(comm: string): string {
+  return posix.basename(comm.trim()).replace(/^-/, "");
+}
+
+const SH_LIKE = new Set(["sh", "bash", "zsh", "dash", "ksh", "ash"]);
+
+/** What `claudep env` prints. PowerShell on Windows outside Git Bash. Then the
+ *  parent process decides when it is a shell claudep knows (fish, pwsh, or an
+ *  sh-like shell); otherwise the login shell in $SHELL: fish when that is
+ *  fish, sh for anything else. fish exports no marker a child could see,
+ *  which is why the parent is consulted at all. `--shell` overrides all of it. */
+export function shellSyntax(
+  env: Env = process.env,
+  platform: NodeJS.Platform = process.platform,
+  parent: string | undefined = undefined,
+): EnvSyntax {
+  if (platform === "win32" && !env.MSYSTEM) return "powershell";
+  const p = parent !== undefined ? shellNameOf(parent) : "";
+  if (p === "fish") return "fish";
+  if (p === "pwsh" || p === "powershell") return "powershell";
+  if (SH_LIKE.has(p)) return "sh";
+  return env.SHELL && posix.basename(env.SHELL) === "fish" ? "fish" : "sh";
+}
+
+/** The syntax for a `--shell` value: the shell-init names plus `sh`. */
+export function envSyntaxOf(name: string): EnvSyntax | undefined {
+  if (name === "sh" || name === "zsh" || name === "bash") return "sh";
+  if (name === "fish" || name === "powershell") return name;
+  return undefined;
+}
+
+/** fish single-quoting: only \ and ' are special inside single quotes. */
+export function fishQuote(s: string): string {
+  return `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
 }
 
 /** The `claudep env` script: pin the shell to `dir`, or clear the pin. */
@@ -1094,12 +1286,81 @@ export function envScript(dir: string | undefined, syntax: EnvSyntax): string {
     // Clearing CLAUDEP_AUTO turns this into a manual pin the shell hook will not touch.
     return `$env:CLAUDE_CONFIG_DIR = '${dir.replace(/'/g, "''")}'\nRemove-Item Env:CLAUDEP_AUTO -ErrorAction SilentlyContinue\n`;
   }
+  if (syntax === "fish") {
+    // A bare `set -e` on a missing name returns 1 and `source` reports its
+    // last status, which prompt themes paint red; the guard keeps it at 0.
+    if (dir === undefined)
+      return "not set -q CLAUDE_CONFIG_DIR; or set -e CLAUDE_CONFIG_DIR\nnot set -q CLAUDEP_AUTO; or set -e CLAUDEP_AUTO\n";
+    return `set -gx CLAUDE_CONFIG_DIR ${fishQuote(dir)}\nnot set -q CLAUDEP_AUTO; or set -e CLAUDEP_AUTO\n`;
+  }
   if (dir === undefined) return "unset CLAUDE_CONFIG_DIR CLAUDEP_AUTO\n";
   return `export CLAUDE_CONFIG_DIR='${dir.replace(/'/g, `'\\''`)}'\nunset CLAUDEP_AUTO\n`;
 }
 
 export function shellInit(shell: Shell, profilesRoot: string, platform: NodeJS.Platform = process.platform): string {
-  return shell === "powershell" ? powershellHook(profilesRoot) : shHook(shell, profilesRoot, platform);
+  if (shell === "powershell") return powershellHook(profilesRoot);
+  if (shell === "fish") return fishHook(profilesRoot);
+  return shHook(shell, profilesRoot, platform);
+}
+
+/** The fish hook. Builtins only (set, test, read, printf, string); every
+ *  `(...)` is a `string` builtin, which runs in-process. Needs fish 3.0:
+ *  `path dirname` would need 3.5 and `$(...)` 3.4, and Ubuntu 22.04 ships
+ *  3.3. fish fires --on-variable on every `set` of PWD, `cd .` included, so
+ *  the last-pwd dedupe stays. Not a Windows target; joins with `/`. */
+function fishHook(profilesRoot: string): string {
+  return `# claudep shell hook. Load it from ~/.config/fish/config.fish:  ${hookHint("fish")}
+set -g _claudep_root ${fishQuote(profilesRoot)}
+function _claudep_auto --on-variable PWD
+  test "$PWD" = "$_claudep_last_pwd"; and return 0
+  set -g _claudep_last_pwd $PWD
+  # Only manage a CLAUDE_CONFIG_DIR this hook set itself. A manual pin wins.
+  if test -n "$CLAUDE_CONFIG_DIR"; and test "$CLAUDE_CONFIG_DIR" != "$CLAUDEP_AUTO"
+    return 0
+  end
+  set -l dir $PWD
+  set -l name ''
+  set -l found ''
+  while true
+    if test -f "$dir/${PIN_FILE}"
+      set found $dir
+      test -n "$found"; or set found /
+      while read -l line
+        set line (string trim -- $line)
+        if test -z "$line"; or string match -q -- '#*' $line
+          continue
+        end
+        set name $line
+        break
+      end < "$dir/${PIN_FILE}"
+      break
+    end
+    if test -z "$dir"; or test "$dir" = /
+      break
+    end
+    set dir (string replace -r -- '/[^/]*$' '' $dir)
+  end
+  if test -z "$name"
+    # No pin here: hand the shell back to the base account.
+    if test -n "$CLAUDEP_AUTO"
+      set -e CLAUDE_CONFIG_DIR
+      set -e CLAUDEP_AUTO
+    end
+    return 0
+  end
+  if not test -d "$_claudep_root/$name"
+    if test -n "$CLAUDEP_AUTO"
+      set -e CLAUDE_CONFIG_DIR
+      set -e CLAUDEP_AUTO
+    end
+    printf 'claudep: %s/${PIN_FILE} names profile "%s", which does not exist. Run: claudep init %s\\n' "$found" "$name" "$name" >&2
+    return 0
+  end
+  set -gx CLAUDE_CONFIG_DIR "$_claudep_root/$name"
+  set -gx CLAUDEP_AUTO "$_claudep_root/$name"
+end
+_claudep_auto
+`;
 }
 
 /** The PowerShell hook, for Windows PowerShell 5.1 and PowerShell 7. Wraps
@@ -1217,10 +1478,190 @@ _claudep_auto
 
 function cmdShellInit(L: Layout, args: string[]): void {
   const shell = args[0] ?? defaultShell(process.env, L.platform);
-  if (!SHELLS.includes(shell as Shell)) die(`unsupported shell "${shell}". Use zsh, bash or powershell`);
+  if (!SHELLS.includes(shell as Shell)) die(`unsupported shell "${shell}". Use ${SHELLS.join(", ")}`);
   process.stdout.write(shellInit(shell as Shell, L.profilesRoot, L.platform));
 }
 
+// ---------------------------------------------------------------------------
+// Tab completions, generated from COMMANDS. Profile names come from a glob
+// over the profiles root at completion time; no script ever runs claudep.
+// ---------------------------------------------------------------------------
+
+/** The one rc-file line that loads the completions. */
+export function completionHint(shell: CompletionShell): string {
+  return shell === "fish" ? "claudep completion fish | source" : `eval "$(claudep completion ${shell})"`;
+}
+
+const visibleCommands = () => COMMANDS.filter((c) => !c.hidden);
+const isList = (arg: Command["arg"]): arg is readonly string[] => arg !== undefined && typeof arg !== "string";
+
+export function completionScript(shell: CompletionShell, profilesRoot: string): string {
+  if (shell === "zsh") return zshCompletion(profilesRoot);
+  if (shell === "bash") return bashCompletion(profilesRoot);
+  return fishCompletion(profilesRoot);
+}
+
+/** Dual-mode: `eval "$(claudep completion zsh)"` after compinit registers it
+ *  with compdef; saved as `_claudep` on fpath, the #compdef line and the
+ *  funcstack check make it autoload. Names come from a glob with (N/:t):
+ *  nothing on an empty root, directories only, basename. */
+function zshCompletion(profilesRoot: string): string {
+  const q = `'${profilesRoot.replace(/'/g, `'\\''`)}'`;
+  const noColon = (s: string) => s.replace(/:/g, "\\:");
+  const cmds = visibleCommands().flatMap((c) => commandWords(c).map((w) => `    '${w}:${noColon(c.desc)}'`));
+  const cases = COMMANDS.filter((c) => c.arg || c.flags || c.valueFlags).map((c) => {
+    const specs: string[] = [];
+    if (c.arg === "profile") specs.push("'1:profile:_claudep_profiles'");
+    else if (c.arg === "dir") specs.push("'1:directory:_files -/'");
+    else if (isList(c.arg)) specs.push(`'1:shell:(${c.arg.join(" ")})'`);
+    if (c.name === "run") specs.push("'*:claude arguments:'");
+    for (const f of c.flags ?? []) specs.push(`'${f}'`);
+    for (const v of c.valueFlags ?? [])
+      specs.push(`'${v.name}=-:${v.name.slice(2)}:${v.values ? `(${v.values.join(" ")})` : ""}'`);
+    return `        ${commandWords(c).join("|")}) _arguments ${specs.join(" ")} ;;`;
+  });
+  return `#compdef claudep
+# claudep completions. Load them after compinit in ~/.zshrc:  ${completionHint("zsh")}
+_claudep_profiles() {
+  local -a names
+  names=(default ${q}/*(N/:t))
+  _describe -t profiles 'profile' names
+}
+_claudep() {
+  local -a cmds
+  cmds=(
+${cmds.join("\n")}
+  )
+  _arguments -C '1:command:->cmd' '*::arg:->args'
+  case $state in
+    cmd)
+      _describe -t commands 'claudep command' cmds
+      _claudep_profiles
+      ;;
+    args)
+      case $words[1] in
+${cases.join("\n")}
+      esac
+      ;;
+  esac
+}
+if [ "\${funcstack[1]}" = "_claudep" ]; then _claudep "$@"; else compdef _claudep claudep; fi
+`;
+}
+
+/** bash 3.2 safe: no mapfile, no compopt. The root's backslashes become
+ *  slashes so a Git Bash user with a C:\\ root still globs. */
+function bashCompletion(profilesRoot: string): string {
+  const q = `'${profilesRoot.replace(/'/g, `'\\''`)}'`;
+  const top = [...visibleCommands().flatMap(commandWords), "default"].join(" ");
+  const flagCases = COMMANDS.filter((c) => c.flags || c.valueFlags).map(
+    (c) =>
+      `        ${commandWords(c).join("|")}) words="${[...(c.flags ?? []), ...(c.valueFlags ?? []).map((v) => v.name)].join(" ")}" ;;`,
+  );
+  const valued = COMMANDS.flatMap((c) => (c.valueFlags ?? []).filter((v) => v.values));
+  const valueBranches = valued.map(
+    (v, i) => `      ${i === 0 ? "if" : "elif"} [ "$prev" = "${v.name}" ]; then words="${(v.values ?? []).join(" ")}"`,
+  );
+  const argCases = COMMANDS.filter((c) => c.arg).map((c) => {
+    const names = commandWords(c).join("|");
+    if (c.arg === "profile") return `          ${names}) words="default $(_claudep_profiles)" ;;`;
+    if (c.arg === "dir") return `          ${names}) COMPREPLY=($(compgen -d -- "$cur")); return 0 ;;`;
+    return `          ${names}) words="${isList(c.arg) ? c.arg.join(" ") : ""}" ;;`;
+  });
+  return `# claudep completions. Load them from ~/.bashrc:  ${completionHint("bash")}
+_claudep_profiles() {
+  local root=${q} d
+  root=\${root//\\\\//}
+  for d in "$root"/*/; do
+    d=\${d%/}
+    [ -d "$d" ] && printf '%s\\n' "\${d##*/}"
+  done
+}
+_claudep() {
+  local cur prev cmd words=""
+  cur=\${COMP_WORDS[COMP_CWORD]}
+  prev=\${COMP_WORDS[COMP_CWORD-1]}
+  cmd=\${COMP_WORDS[1]}
+  COMPREPLY=()
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=($(compgen -W "${top} $(_claudep_profiles)" -- "$cur"))
+    return 0
+  fi
+  case $cur in
+    -*)
+      case $cmd in
+${flagCases.join("\n")}
+      esac
+      ;;
+    *)
+${valueBranches.join("\n")}
+      ${valueBranches.length ? "elif" : "if"} [ "$COMP_CWORD" -eq 2 ]; then
+        case $cmd in
+${argCases.join("\n")}
+        esac
+      fi
+      ;;
+  esac
+  COMPREPLY=($(compgen -W "$words" -- "$cur"))
+}
+complete -F _claudep claudep
+`;
+}
+
+/** The two conditions are written out over `commandline -opc` instead of
+ *  fish's __fish_use_subcommand and __fish_seen_subcommand_from, whose
+ *  names moved between versions. `for` over an unmatched glob runs zero
+ *  times, so an empty root offers only `default`. */
+function fishCompletion(profilesRoot: string): string {
+  const lines: string[] = [];
+  for (const c of visibleCommands())
+    for (const w of commandWords(c))
+      lines.push(`complete -c claudep -n '__claudep_at 1' -a ${w} -d ${fishQuote(c.desc)}`);
+  lines.push("complete -c claudep -n '__claudep_at 1' -a '(__claudep_profiles)' -d profile");
+  const profileCmds = COMMANDS.filter((c) => c.arg === "profile")
+    .flatMap(commandWords)
+    .join(" ");
+  lines.push(
+    `complete -c claudep -n '__claudep_cmd ${profileCmds}; and __claudep_at 2' -a '(__claudep_profiles)' -d profile`,
+  );
+  for (const c of COMMANDS) {
+    const ws = commandWords(c).join(" ");
+    if (isList(c.arg))
+      lines.push(`complete -c claudep -n '__claudep_cmd ${ws}; and __claudep_at 2' -a '${c.arg.join(" ")}'`);
+    if (c.arg === "dir")
+      lines.push(`complete -c claudep -n '__claudep_cmd ${ws}; and __claudep_at 2' -a '(__fish_complete_directories)'`);
+    for (const f of c.flags ?? []) lines.push(`complete -c claudep -n '__claudep_cmd ${ws}' -l ${f.slice(2)}`);
+    for (const v of c.valueFlags ?? [])
+      lines.push(
+        `complete -c claudep -n '__claudep_cmd ${ws}' -l ${v.name.slice(2)} -x${v.values ? ` -a '${v.values.join(" ")}'` : ""}`,
+      );
+  }
+  return `# claudep completions. Load them from ~/.config/fish/config.fish:  ${completionHint("fish")}
+function __claudep_profiles
+  echo default
+  for d in ${fishQuote(profilesRoot)}/*/
+    string replace -r -- '^.*/([^/]+)/$' '$1' $d
+  end
+end
+function __claudep_at -a n
+  test (count (commandline -opc)) -eq $n
+end
+function __claudep_cmd
+  set -l t (commandline -opc)
+  test (count $t) -ge 2; and contains -- $t[2] $argv
+end
+complete -c claudep -f
+${lines.join("\n")}
+`;
+}
+
+function cmdCompletion(L: Layout, args: string[]): void {
+  const shell = args[0] ?? defaultShell(process.env, L.platform);
+  if (!COMPLETION_SHELLS.includes(shell as CompletionShell))
+    die(`no completions for "${shell}". Use ${COMPLETION_SHELLS.join(", ")}`);
+  process.stdout.write(completionScript(shell as CompletionShell, L.profilesRoot));
+}
+
 /** A POSIX-style CLAUDE_CONFIG_DIR on Windows is one claude.exe cannot read. */
 function msysConfigDirWarning(L: Layout, env: Env = process.env): string | undefined {
   const cfg = env.CLAUDE_CONFIG_DIR;
@@ -1230,6 +1671,7 @@ function msysConfigDirWarning(L: Layout, env: Env = process.env): string | undef
 
 async function cmdDoctor(L: Layout, args: string[]): Promise<void> {
   const names = args[0] ? [args[0]] : listProfileNames(L);
+  let problems = 0;
   const launch = findClaude();
   if (launch && launch.kind !== "ps1") {
     const { out } = await captureClaude(L, undefined, ["--version"]);
@@ -1238,11 +1680,29 @@ async function cmdDoctor(L: Layout, args: string[]): Promise<void> {
       console.log(
         `${c.dim("·")} claude is the npm cmd shim and runs through cmd.exe; the native installer's claude.exe avoids that hop`,
       );
+    const v = parseVersion(out);
+    const floor = parseVersion(MIN_CLAUDE_VERSION);
+    if (L.platform === "darwin" && v && floor && versionBelow(v, floor)) {
+      bad(
+        `Claude Code ${v.join(".")} is older than ${MIN_CLAUDE_VERSION}; every config dir shares one Keychain item there, so profiles cannot hold separate logins. Update Claude Code`,
+      );
+      problems++;
+    }
   } else if (launch) bad(`only ${launch.bin} found; claudep needs claude.exe or claude.cmd`);
   else bad("claude binary not found on PATH");
   ok(`base: ${L.base}${L.callerConfigDir && !L.managed ? c.yellow("  (from CLAUDE_CONFIG_DIR in your shell)") : ""}`);
   const msysWarning = msysConfigDirWarning(L);
   if (msysWarning) warn(msysWarning);
+  const settingsFile = join(L.base, "settings.json");
+  const pinnedInSettings = await settingsEnvConfigDir(settingsFile);
+  if (pinnedInSettings !== undefined) {
+    bad(
+      `${settingsFile} sets env.CLAUDE_CONFIG_DIR (${pinnedInSettings}). Claude Code disables features when that differs from the active dir, which it does in every profile. Remove it; pin shells with claudep env or a ${PIN_FILE} file instead`,
+    );
+    problems++;
+  }
+  for (const v of authEnvOverrides(process.env, L.platform))
+    warn(`${v} is set in this shell; Claude Code uses it instead of the profile login, always in -p mode`);
   ok(`profiles root: ${L.profilesRoot}`);
 
   const shared = sharedItems(L.base);
@@ -1256,7 +1716,6 @@ async function cmdDoctor(L: Layout, args: string[]): Promise<void> {
     warn(`base items neither shared nor known-private (they stay per-profile): ${unclassified.join(", ")}`);
   }
 
-  let problems = 0;
   for (const name of names) {
     const dir = profileDir(L, name);
     console.log(`\n${c.bold(name)}  ${c.dim(dir)}`);
@@ -1303,7 +1762,7 @@ async function cmdDoctor(L: Layout, args: string[]): Promise<void> {
 }
 
 async function cmdRm(L: Layout, args: string[]): Promise<void> {
-  const f = parseFlags(args, ["--keep-login", "--yes"], []);
+  const f = parseFlags(args, ...flagSpec("rm"));
   const name = f.rest[0];
   if (!name) die("usage: claudep rm <name> [--keep-login] [--yes]");
   const dir = profileDir(L, name);
@@ -1315,6 +1774,18 @@ async function cmdRm(L: Layout, args: string[]): Promise<void> {
     samePath(real, L.home, L.platform)
   )
     die(`refusing to remove ${real}: not inside ${L.profilesRoot}`);
+  const cur = currentProfile(L);
+  if (cur.kind === "profile" && cur.name === name) {
+    const unset = envUnsetHint(shellSyntax(process.env, L.platform, parentProcessName(L.platform)));
+    warn(
+      `this shell is on ${name} (${cur.setBy === "hook" ? "shell hook" : "manual pin"}). After removal run: ${unset}`,
+    );
+  }
+  const pin = resolvePin(process.cwd());
+  if (pin && pin.name === name)
+    warn(
+      `${shortHome(pin.file, L.home, L.platform)} pins this directory tree to ${name}. Remove it with: claudep local --remove`,
+    );
   if (!f.bools.has("--yes")) {
     const yes = confirm(`Remove profile "${name}" (${dir})? Shared items are only unlinked; ${L.base} is untouched.`);
     if (!yes) {
@@ -1350,26 +1821,38 @@ async function cmdRm(L: Layout, args: string[]): Promise<void> {
 }
 
 function help(L: Layout): void {
+  console.log(helpText(L));
+}
+
+/** Hand-written on purpose: the layout says more than the table can. A test
+ *  checks that every command in COMMANDS appears in it. */
+export function helpText(L: Layout): string {
   const root = shortHome(L.profilesRoot, L.home, L.platform);
-  console.log(`${c.bold("claudep")} ${c.dim(version())}: run Claude Code under separate accounts on one machine
+  return `${c.bold("claudep")} ${c.dim(version())}: run Claude Code under separate accounts on one machine
 
 ${c.bold("USAGE")}
   claudep <name> [claude args…]        run claude with profile <name>  (alias for "run")
   claudep init <name> [options]        create/update a profile and log in
-  claudep list                         show every profile and who it is logged in as
+  claudep list [--json]                show every profile and who it is logged in as
   claudep status <name> [--json]       login state for one profile ("default" = ~/.claude)
-  claudep current [--json]             which profile this shell is on, and why
-  claudep env <name> | --unset         print the CLAUDE_CONFIG_DIR export (or the unset) for eval / Invoke-Expression
+  claudep current [--json|--name]      which profile this shell is on, and why; --name prints only the name
+  claudep env <name> | --unset         print the CLAUDE_CONFIG_DIR pin (or the unset) for eval, source or Invoke-Expression;
+                                       --shell sh|fish|powershell picks the syntax when the shell was not detected
   claudep alias <name> <command>       write a shim so "<command>" == "claudep <name>"
-  claudep doctor [name]                verify symlinks, keychain entry, unclassified files
+  claudep doctor [name]                verify symlinks, keychain entry, unclassified files, Claude Code version
   claudep rm <name> [--keep-login]     log out and delete a profile (base is never touched)
+  claudep help                         show this text
   claudep --version                    print the version
 
 ${c.bold("DIRECTORY PINS")}
   claudep local <name> [--force]       write ./${PIN_FILE} so this tree uses <name>; --remove deletes it
   claudep local                        show the pin that applies to the current directory
   claudep resolve [dir] [--json]       print the profile pinned for a directory (exit 1 when none)
-  claudep shell-init [zsh|bash|powershell]   print the hook that applies pins on cd; load it from your rc file
+  claudep shell-init [${SHELLS.join("|")}]   print the hook that applies pins on cd; load it from your rc file
+
+${c.bold("TAB COMPLETION")}
+  claudep completion [${COMPLETION_SHELLS.join("|")}]   print completions for commands, flags and profile names;
+                                       load them from your rc file (after compinit in zsh)
 
 ${c.bold("INIT OPTIONS")}
   --sso               force the SSO login flow (Enterprise orgs)
@@ -1386,10 +1869,13 @@ ${c.bold("EXAMPLES")}
   claude                                        # Claude Code as whatever ~/.claude is logged in as
   claudep enterprise -p "summarize this repo"
   eval "$(claudep env enterprise)"              # pin the whole shell to a profile
+  claudep env enterprise | source               # the same from fish
   claudep env enterprise | Invoke-Expression    # the same from PowerShell
   claudep local enterprise                      # pin this repo; commit the ${PIN_FILE} file for the team
   eval "$(claudep shell-init zsh)"              # in .zshrc: shells follow ${PIN_FILE} pins on cd
+  ${hookHint("fish")}              # the same line for config.fish
   ${hookHint("powershell")}   # the same line for $PROFILE
+  ${completionHint("zsh")}             # in .zshrc after compinit: tab completion
 
 ${c.bold("HOW IT WORKS")}
   ~/.claude stays exactly as it is and remains the "default" profile. Each named profile is a
@@ -1414,7 +1900,7 @@ ${c.bold("ENVIRONMENT")}
   CLAUDEP_AUTO          set by the hook next to CLAUDE_CONFIG_DIR; marks the pin as hook-managed
 
 ${c.dim("claudep is an independent, unofficial tool. It is not affiliated with, endorsed by or supported by Anthropic.")}
-`);
+`;
 }
 
 // ---------------------------------------------------------------------------
@@ -1437,7 +1923,7 @@ export async function main(argv: string[]): Promise<void> {
       return cmdRun(L, args);
     case "list":
     case "ls":
-      return cmdList(L);
+      return cmdList(L, args);
     case "status":
       return cmdStatus(L, args);
     case "env":
@@ -1450,6 +1936,8 @@ export async function main(argv: string[]): Promise<void> {
       return cmdResolve(L, args);
     case "shell-init":
       return cmdShellInit(L, args);
+    case "completion":
+      return cmdCompletion(L, args);
     case "version":
     case "--version":
     case "-v":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bordoni/claudep",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Unofficial, not affiliated with Anthropic. Run Claude Code under separate accounts on one machine (work + personal) with isolated logins and shared config.",
   "type": "module",
   "license": "MIT",