Commands¶

Fifteen commands, grouped by what you are trying to do. Every one works the same way on macOS, Linux, WSL and Windows.

Switching profiles

Move between accounts, and see which one is active.

claude-profile · claude-profiles
Usage and limits

How much of each account is left, and which has the most room.

--live · claude-best · claude-auto
Sessions

Find past conversations, move one to another account, clear out old ones.

claude-sessions · claude-handoff · claude-clear · claude-prune
Managing profiles

Set a profile up, run one command under it, or delete it.

claude-profile-clone · -exec · -remove
Status line

See the active account from inside a Claude Code session.

claude-profiles statusline
Health and updates

Check the install, and move to a newer version.

claude-doctor · claude-update

Every command¶

Command	Does
`claude-profile NAME`	Switch this shell to a profile, creating it if needed
`claude-profiles`	Every profile, its account, and how much of its limits are used
`claude-profiles --live`	The same, with current figures instead of the cache
`claude-sessions`	List conversations readably
`claude-sessions --grep`	Search every message across every account
`claude-handoff NAME`	Move a conversation to another account and continue there
`claude-best`	Which account has the most headroom
`claude-auto`	Launch Claude on that account automatically
`claude-profile-exec`	Run one command under a profile without switching
`claude-profile-clone`	Seed a new profile's settings from an existing one
`claude-profile-remove`	Delete a profile, its history and its credentials
`claude-clear`	Delete one project's sessions, with a prompt
`claude-prune`	Delete sessions by age, orphaned, or leftovers (dry run by default)
`claude-doctor`	Check the installation for problems
`claude-update`	Check for and pull a newer version
`claude-profiles statusline`	A status line for inside Claude Code

Names used throughout these examples - default, work, client - are placeholders. Profiles can be called anything.

---¶

How the commands are built¶

Shell commands wrap one cross-platform Python core (bin/claude-profiles.py). The core can also be called directly - useful in scripts, or on a shell with no wrapper installed.

Shell command	Core equivalent
`claude-profile NAME`	(shell only - it must export into your session)
`claude-profiles`	`claude-profiles.py status`
`claude-sessions`	`claude-profiles.py sessions`
`claude-handoff`	`claude-profiles.py handoff`
`claude-profile-remove`	`claude-profiles.py remove`
`claude-profile-clone`	`claude-profiles.py clone`
`claude-profile-exec`	(shell only)
`claude-doctor`	`claude-profiles.py doctor`
`claude-clear`	`claude-profiles.py clear`
`claude-prune`	`claude-profiles.py prune`
`claude-best`	`claude-profiles.py best`
`claude-update`	`claude-profiles.py update`
`claude-auto`	(wrapper only)
`claude-path`	`claude-profiles.py path NAME`
`claude-statusline`	`claude-profiles.py statusline`

PowerShell users get the same claude-* names as aliases, plus verb-noun forms:

Alias	PowerShell function
`claude-profile`	`Set-ClaudeProfile`
`claude-profiles`	`Get-ClaudeProfiles`
`claude-sessions`	`Get-ClaudeSessions`
`claude-handoff`	`Move-ClaudeSession`
`claude-clear`	`Remove-ClaudeSessions`
`claude-prune`	`Clear-ClaudeSessions`
`claude-profile-remove`	`Remove-ClaudeProfile`
`claude-profile-clone`	`Copy-ClaudeProfile`
`claude-profile-exec`	`Invoke-ClaudeProfile`
`claude-doctor`	`Test-ClaudeProfiles`
`claude-best`	`Find-ClaudeProfile`
`claude-update`	`Update-ClaudeProfiles`
`claude-path`	`Get-ClaudeProfilePath`
`claude-statusline`	`Set-ClaudeStatusLine`

| claude-auto | Start-ClaudeAuto |

Only claude-profile-exec and claude-auto have no single core subcommand behind them: they set the environment for a child process, which is the shell layer's job rather than the core's.

Calling the core directly¶

Every shell command is a thin wrapper around bin/claude-profiles.py. You can call it yourself - useful in scripts, or on a machine where the shell layer is not installed.

`claude-profiles.py path NAME`¶

Print a profile's config directory. Useful in scripts.

CLAUDE_CONFIG_DIR=$(claude-profiles.py path work) claude -p "summarise this repo"

That form runs a single command under a profile without switching your shell.