CodeHerderSearch⌘KRequest access →

Project defaults for the CLI

Commit a .codeherder.env file so everyone who checks out a repo gets the same server, workspace, and local or cloud setup without exporting anything.

If everyone on your team checks out the same repo and always points ch at the same server and workspace, you can commit that default once instead of asking each person to export it. A .codeherder.env file at the root of a repo gives ch those defaults automatically, for anyone who runs it from inside that checkout. It can also record whether the repo works on your machine or in the cloud, carry settings for the terminal console, and choose how local tasks land their work.

It’s meant to be committed. It never holds a token, a key, or anything else that identifies you — see What it never sets below.

Where it goes, and how ch finds it

Create a file named .codeherder.env at the root of your repository:

cat > .codeherder.env << 'EOF'
CH_ADDR=https://codeherder.example.com
CH_WORKSPACE_ID=acme/platform
EOF

Every ch command walks upward from your current directory looking for that file (apart from ch device-server — see The ch device-server exception below), so it’s found whether you run ch from the repo root or from a subdirectory somewhere inside the checkout. Commit it like any other file:

git add .codeherder.env
git commit -m "Add CodeHerder project defaults"

In a parent folder of repos, put the file in the parent folder. See A parent folder of repos.

Format

The file uses the same KEY=value shape as a shell .env file:

  • One KEY=value pair per line.
  • An optional export prefix is allowed and ignored — export CH_ADDR=... and CH_ADDR=... behave the same way.
  • Wrap a value in single or double quotes if you want to; the quotes are stripped.
  • Lines starting with # are comments, and blank lines are skipped.
  • A line with no = is skipped rather than treated as an error.

The keys it can set

Four keys set where ch points and how the repo connects. CH_LOCAL_DELIVERY and the console settings are covered below. Anything else is ignored (see What it ignores):

Key What it sets
CH_ADDR The server your commands talk to. Set this only if your team runs its own CodeHerder server rather than the CodeHerder cloud.
CH_WORKSPACE_ID The workspace commands operate on — a name, slug, slug path, or UUID; see Managing workspaces.
CH_BACKEND Set it to local to keep ch working on your own machine, even when you have signed in with ch login. Any other value has no effect.
CH_CONNECT Set it to hybrid to mark the repo as a live mirror of the workspace in CH_WORKSPACE_ID. It names a mode and grants no access.

You rarely type CH_BACKEND or CH_CONNECT yourself. ch auth login --connect writes them for you: local adds CH_BACKEND=local, and hybrid adds CH_CONNECT=hybrid next to the address and workspace. Moving the repo to the cloud removes CH_BACKEND=local. A teammate’s clone that reads CH_CONNECT=hybrid joins the same workspace when they run ch auth login. See Move a local repo to the cloud.

Console settings

Keys that start with CH_TUI_ are settings for the terminal console you get from running bare ch: its theme, sidebar, and key bindings. Put them in the file to give a team the same console defaults:

CH_TUI_THEME_DARK=nord
CH_TUI_SIDEBAR_WIDTH=32

These apply to the console only. ch never copies them into your environment, and your own ~/.codeherder/tui.env, an environment variable, or a --tui-set flag all override them. See Customize the terminal console for the full order and the list of settings. A CH_TUI_ name the console doesn’t know gets a warning and is skipped.

How a local task lands its work

CH_LOCAL_DELIVERY chooses what a task on your own machine does with its finished work:

CH_LOCAL_DELIVERY=request
  • branch is the default. The work stays on the task’s branch.
  • request pushes the branch and opens a merge request or pull request for you. The agent needs some setup first. See Land the work as a merge request.

ch reads this key only from the .codeherder.env at the root of the repo the task runs in. It ignores a value in your shell. It doesn’t look in a parent folder. One repo’s choice never carries over to another repo.

Where it sits in precedence

The project file supplies the lowest-precedence default for each key: it’s applied only when your environment doesn’t already have a value for that key. If you’ve exported CH_ADDR, CH_WORKSPACE_ID, CH_BACKEND, or CH_CONNECT yourself, or you’re using a profile or a --workspace/--addr flag, the effective value comes from that source instead. See Credential precedence for how this fits alongside browser sign-in, CH_TOKEN, and profiles.

Because CH_ADDR changes which server your commands talk to, applying it from the project file always prints a notice so it’s never a silent switch:

ch: /path/to/repo/.codeherder.env: applying CH_ADDR=https://codeherder.example.com from the project file — commands now talk to this server

What it ignores

Any key in the file other than CH_ADDR, CH_WORKSPACE_ID, CH_BACKEND, CH_CONNECT, CH_LOCAL_DELIVERY, and the console’s CH_TUI_ settings is ignored, and ch prints a line to say so:

ch: .codeherder.env at /path/to/repo/.codeherder.env: ignoring SOME_OTHER_KEY — not a project-config key

What it never sets

Credentials and session identity are never read from a project file — CH_TOKEN, a profile name, or anything that identifies a signed-in person, agent, or session is rejected outright, with a sharper message:

ch: .codeherder.env at /path/to/repo/.codeherder.env: ignoring CH_TOKEN — credentials and session identity are never read from a project file

This is deliberate: a .codeherder.env file is committed to the repo, so anyone who clones it can read it. It should never carry anything a committer wouldn’t want the whole team — or anyone with read access to the repo — to see.

Two refusals follow from the same principle, both about the server the project file names in CH_ADDR:

  • If the project file sets CH_ADDR and you’re also supplying a bearer token — via CH_TOKEN, --token, or a profile (--profile/CH_PROFILE) — without otherwise confirming you mean to send it to that server, ch refuses:

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

    Exporting CH_ADDR yourself, or passing --addr explicitly, counts as consent and clears the refusal.

  • If the project file sets CH_ADDR and your cached ch login credential was minted against a different server, ch won’t send that credential to the project’s server:

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

Either way, follow the message: run ch login against the server the project file names, or pass --token explicitly.

The ch device-server exception

ch device-server applies no project defaults to its own environment, even when you run it from inside a repo that has a project file. It’s a long-running process, and its environment is inherited by every session it later spawns — a repo-level default has no business leaking into every task that device ever runs. Point a device at a specific server or workspace with its own flags or environment instead; see Managing your devices.

The one key it does read is CH_LOCAL_DELIVERY, and only from each local task’s own repo, to decide how that task lands its work (see How a local task lands its work).

Checking what applied

ch whoami shows whether a project file supplied anything for the current invocation, and which keys. For example, a file that sets the server and workspace prints:

project config: /path/to/repo/.codeherder.env (CH_ADDR, CH_WORKSPACE_ID)

The row lists each key the file applied, so a file with CH_BACKEND=local shows CH_BACKEND too. The row only appears when at least one key was actually applied from the file. If your environment already set every key the file sets, the file’s values were never used, and the row doesn’t show. ch whoami --json carries the same information as projectConfigPath and projectConfigApplied.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close