Reference
Configuration reference
Command line
cc-profiles [--port PORT] [--no-browser]
cc-profiles open [restart|stop] [--port PORT] [--no-browser]
cc-profiles stop [--port PORT]
cc-profiles restart [--port PORT]
cc-profiles install-command [--off]
cc-profiles install-app [--port PORT]
cc-profiles reinstall [--yes]
cc-profiles uninstall [--purge] [--yes]
cc-profiles label
cc-profiles which [PATH] [--dir]
cc-profiles shell-init [zsh|bash]
cc-profiles --version
| Option | Default | Effect |
|---|---|---|
--port PORT |
4777, or CC_PROFILES_PORT |
port to listen on (always on 127.0.0.1) |
--no-browser |
off | do not open the browser |
open |
start the server in the background unless it is already running, open the browser and return at once. Prints the server’s pid; its output goes to ~/.cc-profiles/server.log. Used by the /cc-profiles command (see Getting started). open restart and open stop do the same as restart and stop: they are what /cc-profiles restart and /cc-profiles stop run. Any other word is an error |
|
stop |
stop the server running on the port. A write in progress finishes first; another program on the port is left alone | |
restart |
stop, then open without the browser: use it after an update, then reload the page |
|
install-command |
add the /cc-profiles command to Claude Code: writes commands/cc-profiles.md in every profile that does not share commands, with a backup. Never overwrites a file it did not create, and does nothing if the command is up to date. The server does the same the first time it starts, and later only rewrites outdated copies; you need this command only to add it back where you deleted it. With --off, cc-profiles stops adding and updating it ("slash_command": false in config.json) |
|
install-app |
macOS: put cc-profiles in ~/Applications/cc-profiles.app, an app with its own window, Dock icon and menus (see Mac app). With --port, the app uses that port. Never overwrites an app it did not create, and does nothing if the app is up to date. The server does the same the first time it starts on macOS; later it only rewrites the app when cc-profiles was updated or moved, so an app you delete stays deleted. With --off, the server never adds it ("mac_app": false in config.json) |
|
reinstall |
install cc-profiles again from scratch with the tool it was installed with (pipx install --force, uv tool install --force --reinstall, brew reinstall or pip install --force-reinstall), for when something is broken. Stops the server first and starts it again afterwards if it was running. ~/.cc-profiles (settings, templates, backups) and the profiles are kept. Asks before doing anything; --yes skips the question. A source checkout cannot reinstall itself |
|
uninstall |
remove cc-profiles: stops the server, stops adding /cc-profiles and removes the copies it wrote (with a backup), removes the profile by folder line and the Mac app, then uninstalls the app with the tool it was installed with. Keeps ~/.cc-profiles unless --purge. Never touches the profiles. Asks before doing anything; --yes skips the question. See Uninstall for what stays |
|
label |
print the active profile’s name and exit (see Status line) | |
which [PATH] |
the current folder | print the name of the profile the rules give PATH; with --dir, its config folder as an absolute path. Prints nothing and exits with status 1 when no rule matches, the rule says shared, or it names a profile that no longer exists. Read-only and fast (it does not load the server): it runs every time the profile by folder function starts claude |
shell-init [zsh\|bash] |
from $SHELL |
print the claude shell function of profile by folder, for eval "$(cc-profiles shell-init zsh)" in your shell’s startup file |
--version |
print the version and exit |
You can also run it as a module: python3 -m cc_profiles.
Environment variables
| Variable | Effect |
|---|---|
CC_PROFILES_PORT |
default port; install.sh also restarts a cc-profiles running on it after an update |
CC_PROFILES_HOME |
data folder instead of ~/.cc-profiles |
CC_PROFILES_QUIET |
if set, do not log HTTP requests to the terminal |
CC_PROFILES_INSTALL_DRYRUN |
for tests: the Claude Code installer runs echo instead of installing |
CC_PROFILES_TERMINAL_DRYRUN |
for tests: Open in Terminal writes its script and returns the command instead of opening a terminal; it also turns the feature on outside macOS |
CC_PROFILES_TERMINAL_PLATFORM |
for tests: darwin or linux, the terminals Open in Terminal looks for, whatever the system |
CC_PROFILES_INSTALL_DRYRUN_CODE |
for tests: exit code of the dry-run installer (simulates failures) |
CC_PROFILES_PYPI_URL |
for tests: where Check for updates reads the latest version (a file:// URL), instead of pypi.org |
CC_PROFILES_UPDATE_DRYRUN |
for tests: Update says what it would run instead of updating and restarting |
CC_PROFILES_STDLIB_DIR |
for tests: the folder whose disappearance means Python was updated under the running server (the standard library’s folder by default) |
CC_PROFILES_APP_BINARY |
for tests: the program install-app puts in the Mac app, instead of the one compiled into the package; it also lets the tests build the app on Linux |
CC_PROFILES_INSTALL_KIND |
for tests: how cc-profiles thinks it was installed (pipx, uv, brew or source), for the update, uninstall and reinstall tests |
CC_PROFILES_AUTO_COMMAND |
0: at start, do not add or update /cc-profiles in the profiles (the tests set it) |
CC_PROFILES_PICKER |
the folder dialog of Choose…: none turns it off (the page’s own folder browser opens instead; the tests set it), osascript, zenity or kdialog picks one |
CC_PROFILES_AUTO_APP |
0: at start, do not add the Mac app (the tests set it); one already there is still kept up to date |
CC_PROFILES_AUTO_GITHUB |
0: at start, do not give the profiles their own GitHub CLI folder (the tests set it) |
CC_PROFILES_UPDATE_CHECK |
0: never check PyPI on its own (the tests set it) |
CC_PROFILES_GH_CHECK |
0: never ask gh whose account a signed-in GitHub user really is (the tests set it) |
CC_PROFILES_GH_BINARY |
the gh program asked that question, instead of the one on PATH (the tests point it to a fake gh) |
CC_PROFILES_EXPORT_DIR |
where the automatic exports go, instead of iCloud Drive or ~/.cc-profiles/exports |
CC_PROFILES_EXPORT_TICK |
for tests: seconds between two checks of whether an automatic export is due (900 by default) |
CC_PROFILES_FAULT |
for tests: makes the operation step with that name fail, to test that a failed operation stays restorable |
CC_PROFILES_SOURCE |
for install.sh: install from this folder instead of PyPI |
CLAUDE_CONFIG_DIR |
read by cc-profiles label to know the active profile; when it is set, the profile by folder function leaves it as it is |
~/.cc-profiles/config.json
Written on the first run and updated by the UI. You can edit it by hand while the app is stopped.
If the file is not valid JSON, cc-profiles starts again from the defaults (your profiles are detected again, the rules are the default ones) and keeps your file next to it as config.broken-<date>-<time>.json, so nothing in it is lost: fix the copy and put it back as config.json.
{
"profiles": [
{ "id": "default", "label": "Default", "dir": "~/.claude",
"config": "~/.claude.json", "command": "claude" },
{ "id": "work", "label": "Work", "dir": "~/.claude-work",
"config": "~/.claude-work/.claude.json", "command": "claude-work" }
],
"rules": [
{ "match": "code/work", "profile": "work" },
{ "exact": "~", "profile": "shared" }
],
"search_roots": ["~"],
"backup_keep_days": 90
}
profiles
The order matters: the first profile is the source profile, and badge colors follow the order.
| Field | Meaning |
|---|---|
id |
stable identifier, used by rules; lowercase letters, digits and dashes |
label |
name shown in the UI and printed by cc-profiles label |
dir |
the profile folder (~ is expanded) |
config |
its .claude.json. For ~/.claude it is ~/.claude.json, outside the folder |
command |
the command that starts Claude Code in this profile |
rules
Checked in order; the first match wins. Each rule has a profile (a profile id, or shared) and one of:
| Field | Matches |
|---|---|
match |
any project path that contains this text |
exact |
exactly this path (~ is expanded) |
Defaults on first run: your home folder and / as exact rules, plus /private/var/folders, /private/tmp, /tmp/ and Library/Application Support, all shared.
search_roots
Folders searched (5 levels deep) for candidate folders when relinking an orphan project. Default ["~"]. Folders such as node_modules, Library, build folders and hidden folders are skipped.
backup_keep_days
Optional, 15, 30, 60 or 90 (180 and 365, offered by 0.4.0 and 0.4.1, still work); absent means 90. The backups older than that many days are deleted automatically when cc-profiles starts and once a day while it runs, except kept backups and incomplete backups not restored yet. The cleanup cannot be turned off: mark the backups you want to keep with Keep. Set it from the Backups tab.
mac_app
macOS. Absent until the first start, which adds the Mac app and sets it to true; after that the app is never added again by itself, so one you delete stays deleted. false (cc-profiles install-app --off, or install.sh --no-app) means it is never added; Add Mac app or cc-profiles install-app sets it back to true.
auto_export
Optional, "day" or "week"; absent means off. Every profile is exported that often, conversations included, into iCloud Drive/cc-profiles exports (or ~/.cc-profiles/exports without iCloud Drive), keeping the last 3 of each. Set it from the About panel. The last run is recorded in ~/.cc-profiles/auto-export.json. See Automatic export.
update_check
Optional, true or false; absent means true. With true, cc-profiles asks PyPI for its latest version at most once a day (soon after it starts, then daily while it runs) and shows when a new one is out; it never installs anything on its own. With false, it asks only when you click Check for updates. Set it from the About panel. The last answer is kept in ~/.cc-profiles/update-check.json.
Templates
Profile templates are .zip files in ~/.cc-profiles/templates/<name>.zip, in the export format without conversations, memories or credentials. See Templates.
Files cc-profiles writes outside its data folder
| Path | When |
|---|---|
profile folders and ~/.claude.json |
the operations you run |
~/.local/bin/<command> |
creating, editing or deleting a profile (launcher scripts). Only files containing # managed by cc-profiles are ever rewritten or removed |
~/.config/gh, ~/.config/gh-<id>, ~/.config/gh-accounts |
GitHub CLI folders. At start, each profile without one gets ~/.config/gh-<id> (a copy of config.yml and of hosts.yml without any token line), and GH_CONFIG_DIR in the env of its settings.json; picking an account rewrites the user: line of its hosts.yml, removing an account its entry. At start, a profile without a commit identity gets the one of its account (GIT_AUTHOR_* and GIT_COMMITTER_* in its env). Tokens in the system keychain are never read or written. See A GitHub account per profile |
~/.zshrc, ~/.bashrc, ~/.bash_profile |
only to rename or remove a profile alias that was already there, together with the # Claude Code: comment line above it; and to add or remove the one line ending in # cc-profiles: profile by folder when you turn profile by folder on or off |
terminal
The terminal Open in Terminal uses. On macOS "Terminal", "iTerm" or "Ghostty"; on Linux "GNOME Terminal", "Konsole", "Xfce Terminal", "kitty", "Alacritty", "WezTerm", "Ghostty" or "Default terminal" (x-terminal-emulator). Set from the About panel (cc-profiles settings) when more than one is installed; when unset, or set to one that is gone, the first installed in that order.
Something wrong, unclear or missing on this page? Open an issue on GitHub