# Install / update / uninstall

### npm (recommended)

```bash
npm install -g claude-multiacc     # postinstall wires up the shim, CLI, and scheduled jobs
# or run it once without installing globally:
npx claude-multiacc
```

`claude-multiacc` then wraps everything:

```bash
claude-multiacc                    # install or update the addon (idempotent)
claude-multiacc self-update        # update the running installation + re-install
claude-multiacc list               # Claude pool, via claude-accounts
claude-multiacc codex list         # Codex pool, via codex-accounts
claude-multiacc doctor             # status for both pools
claude-multiacc install --help     # installer options
claude-multiacc uninstall          # keep both account pools
# To delete both pools as well: claude-multiacc uninstall --purge-data
```

After `claude-multiacc uninstall`, `npm uninstall -g claude-multiacc` also removes
the npm package and its command links.

npm links `claude-multiacc`, `claude-accounts`, `codex-accounts`, and `multiacc-select`
into its global bin directory. If `claude-multiacc` works, both account commands work
in that same shell, even when postinstall was skipped. The `claude` and `codex` shims
still need the installer's PATH setup: open a new shell after installation.

If an older installation says `codex-accounts: command not found`, update it:

```bash
npm install -g claude-multiacc@latest
codex-accounts verify
```

Before updating, `claude-multiacc codex verify` runs the same verification through
the existing npm wrapper. For git/npx installs, open a new shell or run the exact
`export PATH=...` command printed by the installer. Run `claude-multiacc install`
if auto-setup was skipped and the pool has no manifest yet.

**Automatic updates:** a globally-installed package re-runs `install.sh` from its own
postinstall, so `npm i -g claude-multiacc@latest` fully updates the shim, CLI, and jobs.
A daily job (launchd on macOS, cron on Linux, 04:07) runs `claude-accounts self-update`
to pull the latest release on its own — `npm i -g claude-multiacc@latest` for npm installs,
`git pull && ./install.sh` for git checkouts; set `CLAUDE_MULTIACC_AUTOUPDATE=0` before install to
opt out. `update-notifier` also prints a one-line nudge when a newer version is on npm.
(Note: newer npm versions gate install scripts; if postinstall is blocked, just run
`claude-multiacc install` once.)

New versions publish to npm automatically from `main` via GitHub Actions
(`.github/workflows/publish.yml`, OIDC Trusted Publishing — no long-lived token after the
first bootstrap publish; `scripts/auto-version.mjs` bumps the patch above the last release).

### From a git checkout

```bash
git clone https://github.com/gowalk-public/claude-multiacc.git
cd claude-multiacc
./install.sh                                           # macOS or Linux, idempotent
./install.sh --server root@1.2.3.4                        # override sync target
git pull && ./install.sh                                  # update (data untouched)
./install.sh --uninstall                # restores stock behavior, keeps account data
./install.sh --uninstall --purge-data   # also deletes both account pools
```

`self-update` auto-detects which of these you used (npm global vs git checkout).

**Servers / machines without repo access:** install via **npm** — the registry is
public, so the daily self-update needs no credentials at all (no rsync, no keys).
A git checkout self-updates too, but only if `git pull` can authenticate; for a
private repo on a server that means a read-only deploy key (the 138 server runs
this way: `core.sshCommand` pinned to its deploy key). A plain copied tree is the
one layout that can NOT self-update — don't ship the addon that way.

What install does (all reversible, nothing else):

- **macOS:** marked PATH block at the END of `~/.zshenv`, `~/.zprofile`, `~/.zshrc`
  (+ `~/.profile` and the bash rc files when they exist) — end-of-file placement
  matters because those files re-prepend `~/.local/bin`. Every copy of the block also
  registers a prompt hook (zsh `precmd` / bash `PROMPT_COMMAND`) that puts the shim
  dir back in front before each prompt, so an rc file interrupted with Ctrl-C or a
  tool that rewrites PATH (conda, nvm, a venv) cannot leave the real binary first at
  the next prompt. `~/.profile` is what `bash -l` / `sh -l` read when there is no
  `~/.bash_profile`, so a launcher that runs `bash -lc claude` reaches the pool too;
  it is created when absent (a stock macOS account has none), and the installer never
  creates `~/.bash_profile` (that would stop bash reading `~/.profile`). launchd agents `com.claude-multiacc.limits` +
  `.codex-limits` (15m Claude / 5m Codex), `.health` + `.codex-health` (weekly Mon morning), and
  `.update` (daily 04:07). Notes when this Mac keeps Claude Code logins in the
  Keychain (the pool reads them; ssh sessions cannot — mint portable tokens for
  accounts that must work from everywhere).
- **Linux (root):** PATH block in `~/.bashrc` + `/etc/profile.d/claude-multiacc.sh`
  (+ `~/.profile`, created when absent — Debian's own `~/.profile` prepends
  `~/.local/bin` after `/etc/profile.d` has run, so the block has to end that file
  too), shim symlinks at `/usr/local/bin/claude` and `/usr/local/bin/codex` (shadow via
  PATH order — on the systemd default PATH too; the original binaries are untouched),
  cron entries for limits/health (both providers) + the daily auto-update.
- Both: `~/.claude-accounts/` and `~/.codex-accounts/`, each with an `accounts.json` manifest.