Zeldoc CLI

zeldoc is Zeldoc.ai's command-line client. It lists the models your API key can use, shows what your key has used and the fields your organization set on it, searches the web through Zeldoc.ai, and saves your API keys so other tools can use them. Coding agents that can run shell commands, such as Claude Code, Codex, OpenCode or Pi, can use it as it is: no plugin or extension needed.

The source is on GitHub under the MIT license.

Install

macOS and Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/zeldoc/zeldoc-cli/releases/latest/download/zeldoc-installer.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -c "irm https://github.com/zeldoc/zeldoc-cli/releases/latest/download/zeldoc-installer.ps1 | iex"

The installer downloads the binary for your platform from the latest release, checks its checksum, and puts it in ~/.local/bin (%USERPROFILE%\.local\bin on Windows). If that directory isn't on your PATH yet, the installer adds it; on macOS and Linux it does so with a line in your shell startup files. Open a new terminal and check the installation:

zeldoc --version

Releases have binaries for macOS (Apple silicon and Intel), Linux (x86_64 and ARM64) and Windows (x86_64).

Update

zeldoc update

zeldoc update installs the latest release in place of the one you have; zeldoc update --check only says whether there is a newer one. Once a day, a command you run in a terminal also checks for a newer release in the background and tells you when there is one. Commands whose output goes to a pipe or a file, as in scripts and coding agents, never check. Set ZELDOC_NO_UPDATE_CHECK=1 to turn the check off.

Log in

Save your API key once:

zeldoc auth login

Paste the key when asked; it isn't shown as you type. The CLI checks the key with Zeldoc.ai before saving it. Need a key? See Generate an API key.

If the ZELDOC_API_KEY environment variable is set, the CLI uses it instead of your default saved key, so an existing setup keeps working without logging in.

Have a key for each customer? Save each one under its own name and pin each project to its key; see Use several API keys.

Command	Does
`zeldoc auth login`	Checks and saves a key; `--profile <name>` saves it under a name
`zeldoc auth list`	Lists the saved keys by name, masked
`zeldoc auth use <name>`	Makes a saved key the default
`zeldoc auth pin <name>`	Makes the current project folder use a saved key
`zeldoc auth status`	Shows which key is in use (masked), why, and whether it works
`zeldoc auth fields`	Shows the fields your organization set on the key
`zeldoc auth token`	Prints the key, for tools that read `ZELDOC_API_KEY`
`zeldoc auth logout`	Deletes the saved key in use

Where the key is saved

Keys are saved in credentials.json in a zeldoc folder:

Platform	Path
Linux	`~/.config/zeldoc/credentials.json`
macOS	`~/Library/Application Support/zeldoc/credentials.json`
Windows	`%APPDATA%\zeldoc\credentials.json`

To keep it somewhere else, set ZELDOC_CONFIG_DIR to another folder. On macOS and Linux only your user can read the file. It isn't encrypted, though: like ZELDOC_API_KEY in your environment, anything that runs as your user can read it, including a coding agent with shell access.

List your models

zeldoc models
zeldoc models --mode chat
zeldoc models --json

zeldoc models shows every model your key can use, with its context window, output limit, your price per 1 million tokens, and what it supports: tool calls, reasoning, image input, PDF input and prompt caching. --mode shows one kind of model, such as chat, embedding or audio_transcription. --json adds cache prices and the reasoning levels each model accepts.

Check your usage

zeldoc usage
zeldoc usage --period today
zeldoc usage --all

zeldoc usage shows what your API key has used: requests, input, output and cached tokens, and cost per model, with a total. Costs are in US dollars, as the dashboard shows them for the key. Zeldoc.ai's own models, such as ZDev, are covered by your subscription and show as 0.

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

MODEL         REQUESTS    INPUT  OUTPUT  CACHE READ  COST $
zdev               120  1200000   34000      800000    1.84
gpt-5.5             42   910000   25000      700000    3.18
TOTAL              162  2110000   59000     1500000    5.02

Monthly limit  $5.02 of $50.00 used this month (10%)
Credits        $87.66 available to the organization
ZDev           Pro plan: 41200000 of 300000000 tokens used this month (14%)

--period is today, week (the last 7 days), month (this calendar month, the default) or last-month. Days start at midnight UTC.
Monthly limit appears when your key has a monthly spend limit. Once it is reached, the key stops working until the next month.
Credits appear when your organization pays with prepaid credits. They are shared by all of the organization's keys. Credits are drawn at Zeldoc.ai's credit prices, so they go down a little faster than the costs above add up.
ZDev appears when the key belongs to you as a ZDev seat holder: how many of your plan's tokens you have used this month, counted over all of your keys (cache reads count a tenth). Once they are used up, ZDev pauses until the 1st, or continues as billed overage if your organization has switched that on.
--all shows every key you saved, one row each, with a total; see Use several API keys.
--json prints exact costs, and the tokens written to the prompt cache.

Only your key's usage is shown, never that of other keys in your organization. Organization admins see the whole organization in the dashboard. New requests can take a minute to appear. If usage isn't shown to your organization, zeldoc usage says so instead.

See your key's fields

zeldoc auth fields
zeldoc auth fields --all
zeldoc auth fields --json

Organizations can label their API keys with fields, such as a team, a project or whether the key is private. Organization admins define the fields and set them on each key in the dashboard. zeldoc auth fields shows your key's name and each of the organization's fields with your key's value, - where it has none:

Key  laptop

FIELD       VALUE
Team        Backend
Project     -
Is private  yes

--all shows the fields of every key you saved. --json prints each value as the API sends it: true or false, the text, or for a field with a list of choices the choice's key, with its label in value_label. Only your own key is shown, and the CLI can't change the fields.

Scripts can ask the same endpoint with the key:

curl -s https://api.zeldoc.ai/v1/zeldoc/key -H "Authorization: Bearer $ZELDOC_API_KEY"

{
  "key_name": "laptop",
  "fields": [
    {"key": "team", "display_name": "Team", "type": "select", "value": "backend", "value_label": "Backend"},
    {"key": "project", "display_name": "Project", "type": "text", "value": null, "value_label": null},
    {"key": "is_private", "display_name": "Is private", "type": "boolean", "value": true, "value_label": null}
  ]
}

type is text, boolean or select, and fields follows the order the dashboard shows. A missing, unknown, expired or blocked key gets 401, and a key that belongs to no organization 403.

Search the web

zeldoc search podman rootless ports below 1024
zeldoc search --engines github,stackoverflow -n 5 axum middleware
zeldoc search --json --time-range week rust release notes

zeldoc search uses Zeldoc.ai's web search endpoint. Several words need no quotes. -n limits the number of results, --engines and --categories pick the search engines, and --json prints the results for scripts. Read Web search for what leaves your machine, and keep personal or confidential information out of queries.

Let your coding agent use it

Any agent that can run shell commands can call zeldoc directly. To make it use Zeldoc.ai's search instead of guessing, add a note to the instructions file it reads, such as AGENTS.md or CLAUDE.md:

## Web search
Search the web with `zeldoc search <query>`. Add `-n 5` to keep the output short and
`--json` when you need to process the results; `zeldoc search --help` lists the filters.

The agent needs to be able to reach your saved key or ZELDOC_API_KEY, which it can when it runs commands as your user.

Use your saved key in other tools

zeldoc auth token prints the key the CLI uses, which in a pinned project is that project's key. It does not create a new key and makes no network call. A program cannot set environment variables in the shell that started it, so use it to set ZELDOC_API_KEY for tools that read it, in your shell profile:

Linux and macOS (bash, zsh). Add to ~/.bashrc or ~/.zshrc:

export ZELDOC_API_KEY="$(zeldoc auth token)"

fish. Add to ~/.config/fish/config.fish:

set -gx ZELDOC_API_KEY (zeldoc auth token)

Windows (PowerShell). Add the line to your PowerShell profile:

if (-not (Test-Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force | Out-Null }
Add-Content -Path $PROFILE -Value '$env:ZELDOC_API_KEY = zeldoc auth token'

Programs started from the Start menu or the Dock

Shell profiles only reach programs started from a terminal. On Windows, set a user environment variable instead: [Environment]::SetEnvironmentVariable("ZELDOC_API_KEY", (zeldoc auth token), "User"). It stores a copy of the key, so run it again after you change key.

Uninstall

On macOS and Linux:

zeldoc auth logout
rm ~/.local/bin/zeldoc
rm -r ~/.config/zeldoc ~/.cache/zeldoc ~/.config/fish/conf.d/zeldoc.env.fish

Then remove the line . "$HOME/.config/zeldoc/env.sh" that the installer added to your shell startup files, such as ~/.profile, ~/.bashrc or ~/.zshrc.

On Windows, run zeldoc auth logout, then delete %USERPROFILE%\.local\bin\zeldoc.exe and the %LOCALAPPDATA%\zeldoc folder.

On macOS the update check is kept in ~/Library/Caches/zeldoc instead of ~/.cache/zeldoc.

Install​

Update​

Log in​

Where the key is saved​

List your models​

Check your usage​

See your key's fields​

Search the web​

Let your coding agent use it​

Use your saved key in other tools​

Uninstall​