Use several API keys

If you work for several customers, you often have a Zeldoc.ai API key for each of them, so that each customer's usage is billed to that customer. The Zeldoc CLI can save all of them and pick the right one for the project you're in, and the OpenCode plugin uses the same key in OpenCode. You don't switch keys by hand: open a customer's project and you're using that customer's key.

Save each key under a name

Save each key once, under a profile name of your choice, such as the customer's name:

zeldoc auth login --profile acme
zeldoc auth login --profile globex

Profile names are letters, digits, -, _ and ., such as acme or globex-eu. Each key is checked with Zeldoc.ai before it is saved. The first key you save becomes the default, which the CLI uses where nothing else picks a key.

zeldoc auth list            # the saved profiles, with the default marked
zeldoc auth use globex      # make globex the default
zeldoc auth logout --profile acme

zeldoc auth list shows each key masked, like sk-…a1b2. All keys are saved in the same file as a single key; see Where the key is saved.

Pin a project to a key

In the customer's project folder, run:

cd ~/work/acme-app
zeldoc auth pin acme

This writes a file called .zeldoc-profile containing the profile name. In that folder and every folder below it, the CLI and the OpenCode plugin use the key saved as acme.

The file holds only the name, never the key, so you can commit it to the project's repository. Everyone on the project then saves their own key under that name by running zeldoc auth login in the project folder: in a pinned folder, login saves the key under the pinned name.

No key, no fallback

If a project is pinned to a profile you haven't saved, the CLI and the OpenCode plugin stop with an error that says so. They never use another of your keys instead, because that key may belong to another customer, who would then be billed for the work.

Which key is used

The CLI picks the first of these that applies:

1. --profile <name> on the command, or the ZELDOC_PROFILE environment variable
2. a .zeldoc-profile file in the current folder or the nearest folder above it
3. the ZELDOC_API_KEY environment variable
4. the default profile

A pin wins over ZELDOC_API_KEY, so pins also work if your shell profile sets that variable for every terminal. On a machine where no keys are saved, such as a CI server, pins are ignored and ZELDOC_API_KEY is used.

To see which key is in use and why, run:

zeldoc auth status

API key: sk-…a1b2 (profile `acme`, pinned by /home/you/work/acme-app/.zeldoc-profile)
Zeldoc.ai accepts the key. It can use 12 models.

To use another saved key for one command, add --profile:

zeldoc models --profile globex

In OpenCode

With the Zeldoc plugin installed, OpenCode follows the pins too. In a project with a .zeldoc-profile file, the plugin asks the CLI for that project's key and OpenCode uses it for the model list and for every Zeldoc.ai request, instead of the key from opencode auth login or ZELDOC_API_KEY. The model picker shows the models that customer's key can use.

• Projects without a pin work as before, with the key you connected in OpenCode. They don't need the CLI.
• Pinned projects need the CLI installed. The plugin finds it on your PATH, or in ~/.local/bin, where the installer puts it.
• After changing a pin, restart OpenCode 1 in that project. OpenCode 2 picks up the change with the next request.

If a pinned project's key can't be found, Zeldoc.ai requests in OpenCode fail with a message that says why, for example:

Error: Zeldoc: /home/you/work/initech-app/.zeldoc-profile picks profile `initech`, but no
API key is saved under that name. Run `zeldoc auth login` in this folder to save one

In other tools

Tools without a Zeldoc plugin, such as Claude Code, Codex, Pi or an OpenAI SDK, read the key from ZELDOC_API_KEY. zeldoc auth token prints the key for the current folder, so you can set the variable per project.

On macOS and Linux, direnv does this automatically when you enter the folder. Add a file called .envrc to the project:

export ZELDOC_API_KEY="$(zeldoc auth token)"

and allow it once with direnv allow. Every tool started in that folder then gets the pinned key. Don't commit the .envrc if your team doesn't use direnv; the .zeldoc-profile file is enough for the CLI and OpenCode.

Without direnv, set the variable in the terminal where you start the tool:

export ZELDOC_API_KEY="$(zeldoc auth token)"     # bash, zsh
set -gx ZELDOC_API_KEY (zeldoc auth token)        # fish

$env:ZELDOC_API_KEY = zeldoc auth token           # PowerShell

See each key's usage

zeldoc usage shows what the key for the current folder has used, and --all shows every saved key, one row each, with a total:

zeldoc usage --all

Period  this month, 2026-10-01 to 2026-10-05 (UTC)

PROFILE  KEY        REQUESTS    INPUT  OUTPUT  COST $  MONTHLY LIMIT
acme     laptop          162  2110000   59000    3.18  6% of $50.00
globex   (no name)        40   310000    9000    0.92  -
TOTAL                    202  2420000   68000    4.10

See Check your usage for the periods and what each column means.