CLI overview

@zespan/cli is a small, dependency-free command-line tool. It ships two binaries:

Binary	What it runs	Status
`zespan`	The full command registry — `auth`, `link`, `projects`, `doctor`, `policy` and `gate` as subcommands	New
`zespan-gate`	The CI quality gate directly, with no subcommand	Unchanged

zespan-gate is not deprecated and nothing about it changed. If you already call zespan-gate from a CI pipeline, keep doing exactly that — zespan gate is the same logic reachable through the new binary, not a replacement for it.

Install

npm install --save-dev @zespan/cli

pnpm add -D @zespan/cli

yarn add -D @zespan/cli

This installs both zespan and zespan-gate into node_modules/.bin. You can also run either without installing:

npx @zespan/cli doctor
npx @zespan/cli gate --name my-prompt --version 3 --dataset-run-id run_abc123 --evaluator-id eval_def456

Commands

Usage: zespan <command> [flags]

Commands:
  auth     Sign in to your Zespan account from this machine (login, status, logout)
  link     Choose the project this directory belongs to
  projects List every project your sign-in can reach (projects list)
  doctor   Diagnose SDK setup issues (config, connectivity, data flow, redaction)
  policy   Manage policy-as-code files (init, validate, plan, apply)
  gate     CI quality gate for prompt versions (same binary as zespan-gate)

Flags:
  --help      Show this help
  --version   Print the CLI version

Run `zespan doctor --help`-style flags directly on the doctor command, e.g.:
  zespan doctor --json
  zespan doctor --project <id> --api-key <key>

That’s the literal output of zespan --help (also shown by zespan with no arguments). An unrecognized command prints the same text to stderr and exits 2.

zespan auth — signs this machine in as you, with an OAuth 2.0 device grant a human approves in the browser. See zespan auth.
zespan link / zespan projects list — choose the project a directory belongs to, and list every project you can reach. See zespan link.
zespan doctor — diagnoses SDK setup problems: bad or missing API key, unreachable API, no data arriving, PII redaction posture, and the most common “I installed the SDK and see nothing” mistake. See zespan doctor.
zespan policy — authors, plans and applies guardrail policy-as-code files. See zespan policy.
zespan gate — gates a prompt version’s quality in CI. Identical to zespan-gate; see CI quality gate for the full flag reference and exit code contract.

Two credentials, two planes

The CLI can hold two credentials, and they are not interchangeable. Which one a command uses is decided by what the command does, not by which one you happen to have set.

	Data plane	Control plane
Credential	Project API key	Your user session
Sent as	`x-api-key` header	`Authorization: Bearer` header
Obtained from	Settings → API Keys	`zespan auth login`
Identifies	One project	One person, with a role in each organization
Used by	The SDKs, `/v1/ingest`, guardrail checks, `zespan doctor`, `zespan gate`	`zespan policy pull` / `test` / `plan` / `apply`, `zespan link`, `zespan projects list`

An API key cannot run a control-plane command. Those routes check your role in the organization, and a key authenticates a project — there is no role to check. zespan policy plan with only ZESPAN_API_KEY set now refuses with an explanation instead of sending a request that could only be rejected. Run zespan auth login first.

If both are available, the sign-in wins on the control plane and the API key is left untouched for the data plane — the two identities never silently mix. A stored sign-in that is expired, or that was minted against a different API host, produces a refusal naming the fix rather than a quiet fallback to the API key.

Configuration file — `.zespan.yaml`

Both zespan commands read an optional .zespan.yaml from the current working directory. It supports a flat key: value format only — no nested maps, lists, or multi-line scalars. A line the parser can’t make sense of is silently ignored rather than rejected, so a .zespan.yaml written for a future CLI version degrades gracefully on an older one instead of breaking it.

.zespan.yaml

project: 3f9c2e10-...
environment: production

Key	Aliases	Maps to
`project`	`projectId`	Project id
`environment`	`env`	Environment name

.zespan.yaml never carries your API key or your API URL, even though the parser would technically accept apiKey: or apiUrl: lines — neither key is in the recognized set, and both are silently ignored. This is deliberate, not an oversight: .zespan.yaml is meant to be committed to your repository, and a secret in a committed file is a leaked secret. A committed file that could choose where your key gets sent is the same leak in one more hop — a malicious apiUrl could redirect your ZESPAN_API_KEY to an attacker-controlled host via the x-api-key header. Set the API key only via --api-key or ZESPAN_API_KEY, and the API URL only via --api-url or ZESPAN_API_URL.

Environment variables

Variable	Equivalent flag	Notes
`ZESPAN_API_KEY`	`--api-key`	Never read from `.zespan.yaml` — see above.
`ZESPAN_API_URL`	`--api-url`	Never read from `.zespan.yaml` — see above. Defaults to `https://api.zespan.com/v1`.
`ZESPAN_PROJECT_ID`	`--project`	Set this when it should differ from the project your API key resolves to. If it’s set AND doesn’t match, `doctor`’s Data flow check fails with a plain “wrong project” diagnosis instead of a raw HTTP 403.
`ZESPAN_ENVIRONMENT`	`--env`	Surfaced by `doctor`’s Environment check, and recorded by `zespan link` as this directory’s default environment.
`ZESPAN_APP_URL`	`--app-url`	`zespan auth login` only. The dashboard origin to open the approval page on. Normally unnecessary — the API tells the CLI where to send you.

Precedence

For every value except the API key and the API URL: flags > environment variable > .zespan/config.json > .zespan.yaml > built-in default. The API key and the API URL both skip both files entirely — they only ever come from --api-key/ZESPAN_API_KEY and --api-url/ZESPAN_API_URL respectively. .zespan/config.json is written by zespan link and carries the project and org. It sits above .zespan.yaml because it is the newer, explicit act; a project with no .zespan/config.json behaves exactly as before.

Next steps

zespan auth

zespan link

Link a project to a directory, and list what you can reach.

zespan doctor

What each check verifies, sample output, and how to read a failure.

zespan policy

Author, plan and apply guardrail policies from your repository.

CI quality gate

The zespan gate / zespan-gate flag reference and exit code contract.

API keys

Create and rotate the key zespan doctor and zespan gate authenticate with.

Overview

CLI

TypeScript SDK

Python SDK

Advanced SDK Configuration

Integrations

LLM Providers

Agent Frameworks

RAG Frameworks

Gateways

Vector Databases

Custom / Other

Guides

Install

Commands

Two credentials, two planes

Configuration file — `.zespan.yaml`

Environment variables

Precedence

Next steps

zespan auth

zespan link

zespan doctor

zespan policy

CI quality gate

API keys

​Install

​Commands

​Two credentials, two planes

​Configuration file — .zespan.yaml

​Environment variables

​Precedence

​Next steps

zespan auth

zespan link

zespan doctor

zespan policy

CI quality gate

API keys

Install

Commands

Two credentials, two planes

Configuration file — `.zespan.yaml`

Environment variables

Precedence

Next steps