Credentials and profiles

The ch CLI authenticates in two ways: browser sign-in (the easiest path for interactive use) or an API key (required for agents, CI, and automated scripts). Either way, you must also tell it which workspace to operate on — or commit a project defaults file so your whole team gets the same server and workspace automatically.

This page covers the CLI. If your account is on the Enterprise plan and signs people into the web app through your own identity provider, see Single sign-on (SAML) — it’s a separate path and doesn’t change how the CLI authenticates.

Variable	What it holds	Default
CH_TOKEN	Your API key. Required for the API-key authentication path.	(none)
CH_WORKSPACE_ID	The workspace commands operate on — a name, slug, slug path, or UUID, despite the variable’s name. Most ch verbs are workspace-scoped and read this automatically.	(none — required for workspace commands)
CH_ADDR	The API base URL of your CodeHerder server.	{{api_base}}

Neither value comes from a single page. For CH_WORKSPACE_ID, list your workspaces — with their IDs, names, and slugs — with ch workspace list; any of those forms works, so you don’t have to copy a UUID. For CH_TOKEN: browser sign-in (below) caches a credential automatically, with nothing to copy, and an API key you can export yourself comes from a member’s page under Set up → Members or ch member keys create — see Minting API keys.

You can also select the workspace on a per-command basis with --workspace <ref>, which overrides CH_WORKSPACE_ID for that invocation. A workspace reference can be a name, slug, slug path, or UUID — see Referring to things on the command line for the rules:

ch --workspace acme/platform task list

See Managing workspaces for the full workspace-selection order and how to find your workspace ID.

Browser sign-in

Run ch login to open your browser and sign in to CodeHerder:

ch login

This opens your default browser, completes the sign-in flow, and caches your credentials securely. The first time you do this on a given machine, it also asks you to approve the sign-in from that browser tab — approve it once, and every later ch login on that machine skips the extra step. Subsequent ch commands authenticate automatically — you do not need to set CH_TOKEN.

To sign out and remove the cached credentials:

ch logout

ch logout revokes this installation’s credential on the server first, then removes the cached credential from this machine. Pass --local-only to skip the server-side revoke and only clear the local cache. Either way, it does not affect any API keys or profile files you have configured. To revoke a machine or API key you no longer have access to, see My work.

API key

For agents, CI pipelines, and any non-interactive scenario, export your API key directly:

export CH_TOKEN=<your-api-key>
export CH_WORKSPACE_ID=<your-workspace-id>

Add these to your shell profile (~/.zshrc, ~/.bashrc, or equivalent) so they persist across terminal sessions.

When credentials expire

Some credentials never expire on their own. On a self-hosted server, revoke them by hand.

• API keys for people do not expire.
• CLI sign-in on a machine renews itself and does not expire.
• Device tokens do not expire.

To revoke one credential:

• CLI sign-in on this machine: ch logout.
• An API key: ch member keys delete <hash>. Find the hash with ch member keys <memberRef>.
• A device: ch device rotate-token <deviceRef>, or see My work.

To revoke everything one person holds, an instance operator runs:

ch human revoke-all <humanRef> --yes

This calls POST /v1/instance/humans/{id}/revoke-all. It revokes every API key, MCP grant, device token and CLI installation of that person. It does not disable their sign-in. Disable the user in your identity provider as well.

Bootstrapping the first account (self-hosted)

If you’re running a self-hosted CodeHerder server that doesn’t offer browser sign-in, use ch human bootstrap once to create the first workspace, human account, and API key. Cloud users should use ch login or the web sign-up flow instead. See Self-hosted deployment for downloading and starting the server itself. A fresh server admits the first verified caller as its first account. Create it before you expose the server. See Create the first account.

ch human bootstrap is interactive and email-verified — it does not hand you a key in a single step:

1. Run the command with the email you want to sign in with:

   ch human bootstrap --email you@example.com --display-name "Your Name" --workspace-name "My Workspace"

2. The CLI completes a quick automatic verification step on its own — you’ll see a brief “verifying…” message, but there’s nothing for you to do.

3. CodeHerder emails a one-time 6-digit code to the address you passed.

4. Paste that code at the CLI’s prompt.

5. Once the code checks out, the CLI writes your credentials — printed as an env-block for you to save, or written straight to ~/.codeherder/<name>.env if you passed --install-as <name>. The API key is shown only this once, so save it right away.

You need access to the inbox for the --email address you passed — the code only goes there. Each code is one-time and expires; if it doesn’t arrive or stops working, just re-run ch human bootstrap to request a fresh one.

If a server has turned off self-service signup, ch human bootstrap reports that signup is closed on that server. In that case, ask your administrator for an API key instead.

ch human verify completes the emailed-code step separately from ch human bootstrap, non-interactively — for when you already have a verification ID and the emailed code (for example, if the interactive prompt above was interrupted after the code was sent). It takes --verification-id, --code, and --email (all required), plus the same optional --install-as <name>:

ch human verify --verification-id <id> --code <6-digit> --email you@example.com --install-as me

Verify your connection

Once signed in, confirm the CLI can reach CodeHerder and recognise your identity:

ch whoami

This prints your display name, member ID, and home workspace, along with the server endpoint it reached and its version. When the server build is stamped, it also shows a short build reference next to the version — see Confirm which build is live for why that matters on a self-hosted server. It’s a quick way to confirm you’re signed in and talking to the right server. It does not confirm that CH_WORKSPACE_ID (or --workspace) resolves to anything: it always reports your home workspace, regardless of what either is set to. To check the workspace you’ve actually set, scope the call explicitly:

ch whoami --workspace <ref>

This prints your home workspace, the workspace <ref> resolves to, and your role there — none rather than an error if you’re not a member of it. Pass $CH_WORKSPACE_ID as <ref> to confirm the variable you exported actually works. If you see an error, double-check that you are signed in (ch login or CH_TOKEN) and that your workspace is set (CH_WORKSPACE_ID or --workspace) — see Troubleshooting sign-in below for the specific messages.

If a project defaults file supplied CH_ADDR or CH_WORKSPACE_ID for this command, ch whoami also prints a project config row naming the file and which keys it set — so a surprising server or workspace is traceable to its source in one command. The row appears only when at least one key was actually applied.

Profiles

A profile is a named credential file at ~/.codeherder/<name>.env. Profiles let you keep multiple credential sets and switch between them without editing your shell profile. The file is written at mode 0600 so its contents are readable only by your own account.

Creating a profile

Commands that mint a new API key accept --install-as <name> to write the credentials directly to ~/.codeherder/<name>.env in one step:

# Mint a key for an existing member
ch member keys create <memberId> --install-as laptop

# Create an agent and mint its key in one call
ch agent create --display-name Builder --mint-key --install-as builder

Minting a key for a person needs the Pro plan; minting one for an agent is unaffected — see Plans and limits.

ch human bootstrap also accepts --install-as, but it isn’t a one-step mint — it writes the profile only after you complete an email verification step. See Bootstrapping the first account below.

Without --install-as, the same commands print the env-block to standard output so you can save it manually:

cat > ~/.codeherder/staging.env << 'EOF'
export CH_ADDR={{api_base}}
export CH_TOKEN=ch_...
export CH_WORKSPACE_ID=019e...
EOF
chmod 600 ~/.codeherder/staging.env

Using a profile

There are two ways to activate a profile, and they behave differently with respect to the workspace.

source — loads all variables, including the workspace:

source ~/.codeherder/staging.env

source runs the file in your current shell, setting every variable it contains — including CH_WORKSPACE_ID. Use source when you want to switch both identity and workspace at once.

--profile or CH_PROFILE — loads credentials, never the workspace:

ch --profile staging task list

or, to apply it to every command in a shell session:

export CH_PROFILE=staging

When --profile or CH_PROFILE is set, the CLI reads the named file and applies the token (CH_TOKEN) and server address (CH_ADDR). A profile never sets the workspace — that always comes from CH_WORKSPACE_ID or a --workspace flag, regardless of which profile (if any) is active. Use this form when you want to authenticate as a different user but keep working in the same workspace. To switch workspace at the same time, use source, or pass --workspace alongside --profile.

Credential precedence

The CLI resolves credentials in this order — later sources override earlier ones:

1. A committed project defaults file (.codeherder.env) — the lowest tier, and the only source that applies before you set anything in your shell. It never carries CH_TOKEN or any other credential.
2. Cached browser sign-in from ch login (used only if no explicit token is set)
3. CH_* environment variables (override the browser sign-in cache)
4. The profile named by CH_PROFILE (overrides the env vars above)
5. The profile named by --profile (overrides CH_PROFILE)
6. Explicit per-command flags (--token, --addr) — always win

In practice: use ch login for day-to-day interactive work; export CH_TOKEN or load a profile to authenticate as a specific identity (such as an agent key or a different workspace), and use explicit flags for one-off overrides. Commit a project defaults file only for values every checkout of a repo should share, like which server your team runs.

Troubleshooting sign-in

ch login doesn’t seem to take effect. If CH_TOKEN is exported in your shell, or a profile is active via CH_PROFILE or --profile, that credential overrides the browser sign-in cache — silently, with no warning printed at sign-in time. If commands keep authenticating as the wrong identity after ch login, check whether CH_TOKEN or CH_PROFILE is set in your environment and unset whichever one is taking precedence.

A “no token” error:

no token: set CH_TOKEN, pass --token, or use --profile

None of the credential sources — browser sign-in, CH_TOKEN, or a profile — resolved to a token. Run ch login to sign in with your browser, or set CH_TOKEN (and CH_WORKSPACE_ID) directly.

An expired browser sign-in. If your cached sign-in has expired, the CLI tells you so and asks you to run ch login again. You may see the “no token” error above right after it, if nothing else is configured as a fallback. Re-running ch login refreshes the cache.

A self-hosted server without browser sign-in. Not every CodeHerder server offers the browser sign-in flow. If ch login exits saying the server has no browser sign-in configured, use the API-key path instead: follow Bootstrapping the first account to create one with ch human bootstrap, or paste an existing key into CH_TOKEN or a profile file. If the server has closed self-service signup, ch human bootstrap tells you so — ask your administrator for a key instead.

A loose-permissions warning on the sign-in cache. The CLI stores your browser sign-in at mode 0600 (readable only by your account) under ~/.codeherder/. If those permissions are ever widened — for example by a manual copy or a backup restore — the CLI refuses to use the cache and warns you, naming the file. chmod 600 the path it names, or delete the file and run ch login again.

A refusal naming your .codeherder.env. If a repo you’re working in has committed a project defaults file that sets CH_ADDR, and you’re also supplying a token (via CH_TOKEN, --token, or a profile) without otherwise confirming the server, ch refuses rather than send your token somewhere the repo chose without asking you:

ch: <path>/.codeherder.env declares CH_ADDR=<addr> — refusing to send your bearer token there without your consent. Export CH_ADDR=<addr> yourself, or pass --addr <addr>, if you mean it.

If instead your cached ch login credential is for a different server than the one the project file names, ch refuses to send that credential to the project’s server:

ch: <path>/.codeherder.env declares CH_ADDR=<addr>, but your cached credential (`ch login`) is for a different server (<other addr>) — refusing to send it there. Run `ch login` against <addr>, or pass --token.

Either way, do what the message says: run ch login against the address the project file names, or pass --token explicitly.