Credentials and profiles

How to sign in with your browser or configure an API key, verify your connection, and save named credential 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.

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. Only set this if you are pointing at a server other than the CodeHerder cloud.	`https://api.codeherder.com`

Both CH_TOKEN and CH_WORKSPACE_ID appear on the Install CLI page in your workspace sidebar (under Set up).

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.

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. 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 removes only the browser sign-in cache. It does not affect any API keys or profile files you have configured.

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.

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.

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

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"

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.
CodeHerder emails a one-time 6-digit code to the address you passed.
Paste that code at the CLI’s prompt.
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 workspace, along with the server endpoint it reached and the server’s version — a quick way to confirm you’re talking to the right server. 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.

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 mint-key <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=https://api.codeherder.com
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:

Cached browser sign-in from ch login (used only if no explicit token is set — the lowest tier)
CH_* environment variables (override the browser sign-in cache)
The profile named by CH_PROFILE (overrides the env vars above)
The profile named by --profile (overrides CH_PROFILE)
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.

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.

Browser sign-in