Profile CLI docs

v0.2.1 field manual

Operate profiles.
Keep lanes clear.

Install, create, launch, diagnose, share, and remove profile commands without crossing account or data boundaries.

Start in three steps Open command index

01Install once

02Name a lane

03Launch anywhere

00Background services

01 / REQUIREMENTS

Check the ground first.

Three tools must resolve before a profile command can launch.

Node.js 22+

Node.js 24 LTS recommended. npm must be available in the same terminal.

Claude Code

The official claude executable must already resolve on PATH.

Supported OS

Windows 10/11/Server, Node-supported Linux, or Node-supported macOS.

Windows prefix check

If npm prefix -g contains &, configure a writable prefix without shell metacharacters before installing. Spaces are supported.

02 / QUICK START

First profile in three moves.

The combined add command creates the directory, creates a launcher, opens Claude Code login, and repairs onboarding state.

  1. 01

    Install globally

    Install the public package, then validate the environment.

    Terminal 
    npm install -g @nathanpixodeo/claude-profile-manager

    Environment check 
    claude-profiles doctor

  2. 02

    Create an authorized lane

    team becomes the profile name; claude-team becomes its direct launcher.

    Create + launcher + login 
    claude-profiles add team --command claude-team --login

  3. 03

    Launch from any project

    Generated launchers forward Claude arguments and preserve Claude's exit code.

    Named launcher 
    claude-team
claude-team --continue
claude-team --resume

Keep the default lane intact

Run native claude for the reserved max profile at ~/.claude. Named launchers use isolated directories.

03 / COMMAND INDEX

One surface. Four jobs.

Run claude-profiles --help for the same canonical command surface in your terminal.

01 Profiles

claude-profiles
Open the interactive terminal menu when a TTY is available.
claude-profiles list
List profile name, authentication state, and directory.
claude-profiles add <profile> [--command <claude-name>] [--login]
Create an isolated profile and managed launcher; optionally authenticate immediately.

02 Launch

claude-profiles run <profile> [--] [claude arguments...]
Launch a profile and forward the complete Claude argument array.
claude-profiles continue <profile>
Launch with --continue.
claude-profiles resume <profile>
Launch with --resume.
claude-profiles login <profile>
Run Claude Code's official login flow. Re-login for reserved max is blocked.
claude-profiles status <profile>
Run Claude Code authentication status inside the selected profile.

03 Maintenance

claude-profiles diagnose <profile>
Inspect profile onboarding and shared-directory state.
claude-profiles repair-onboarding <profile>
Repair onboarding metadata without copying credentials.
claude-profiles share-sessions <profile> [--backup-existing]
Link default project sessions after explicit ownership and backup checks.
claude-profiles share-skills <profile> [--backup-existing]
Link default user skills under the same safety rules.
claude-profiles doctor
Check Node.js, npm, Claude Code, storage, and command-directory readiness.

04 Launchers

claude-profiles command create <profile> [claude-command]
Create or rename one managed launcher.
claude-profiles command remove <claude-command>
Remove one managed launcher while keeping profile data.
claude-profiles command list
Show launcher-to-profile mappings and state.
claude-profiles command sync
Rebuild managed launchers for existing named profiles.
claude-profiles command clean
Remove generated launchers but preserve mappings for reinstall.
Using legacy v2 flags?

--list, --use, --diagnose, --repair-onboarding, sharing flags, and command-management flags remain supported. Prefer the canonical commands above for new scripts.

04 / ISOLATION MAP

Know what lives where.

Profile configuration stays local. Launchers route; they do not merge accounts.

DEFAULT / MAX~/.claudenative claude
NAMED PROFILE~/.claude-profiles/<name>CLAUDE_CONFIG_DIR
MAPPINGS~/.claude-profiles/.npm-commands.jsonlauncher registry
LAUNCHERSglobal npm executable directory.cmd or POSIX
  • Credentials: never printed, copied, moved, bundled, or deleted.
  • Sessions and skills: isolated until you explicitly link them.
  • Plugins, history, and state: remain inside each profile directory.
  • Billing and limits: unchanged by separate directories or launchers.

05 / CONTROLLED SHARING

Link data only when ownership matches.

Sharing uses an NTFS junction on Windows or a directory symbolic link on Linux/macOS.

Existing local data stops the command

Exit code 2 means nothing changed. Close other Claude sessions, verify disclosure rights, then rerun with --backup-existing. Existing data moves to a timestamped, recoverable backup before linking.

Never open the same shared session concurrently from two profiles. Never link across people, employers, customers, or organizations without every required right and approval.

06 / TROUBLESHOOTING

Read the lane before repairing it.

Start with doctor, then use the narrow check matching the symptom.

doctorstatusdiagnoserepair
Generated command is not found

Check environment and mapping state, then rebuild managed launchers.

claude-profiles doctor
claude-profiles command list
claude-profiles command sync

Inspect resolution with where.exe claude-team on Windows or command -v claude-team on Linux/macOS.

Profile is not signed in 
claude-profiles status team
claude-profiles login team

Login uses Claude Code's official flow. Re-login for reserved max is intentionally blocked.

Onboarding repeats or profile state looks wrong 
claude-profiles diagnose team
claude-profiles repair-onboarding team

Repair onboarding metadata only; credentials remain untouched.

Sharing exits with code 2

Existing local sessions or skills were detected. Close Claude sessions, review the boundary, then opt into a recoverable backup:

claude-profiles share-sessions team --backup-existing
Windows global npm commands fail before launch 
npm prefix -g

If the prefix contains &, move it to a writable path without shell metacharacters and ensure that directory is on PATH.

07 / UNINSTALL

Remove launchers. Keep profile data.

Clean generated commands before uninstalling the npm package.

Safe removal order 
claude-profiles command clean
npm uninstall -g @nathanpixodeo/claude-profile-manager

Retained: profile directories, command mappings, sessions, state, skills, and credentials. No lifecycle script deletes them.

08 / AUTHORIZED USE

Isolation is not a limit bypass.

Use only accounts you own or are explicitly authorized to administer.

Separate directories do not aggregate, extend, evade, or alter billing, subscription allowances, rate limits, bans, safeguards, product restrictions, or regional access.

The tool does not proxy, intercept, modify, or automate Anthropic requests. Authentication remains inside Claude Code.

Read: Packaged Notice, Consumer Terms, Commercial Terms, Usage Policy, and Supported Regions.