Skip to main content
zespan link records which Zespan project the current directory belongs to, so zespan policy plan and apply do not need a project id on the command line. zespan projects list prints the same data without prompting, which is what CI needs.
Both commands need a user session — run zespan auth login first. An API key authenticates a project, not a person, so it cannot answer “which projects can you reach?”.

​
Quick start

The picker groups projects under the organization that owns them, and every row carries the org name alongside the project name — because the ambiguity this command exists to resolve, the same project name in two organizations, is invisible from the project name alone.

​
.zespan/config.json

.zespan/config.json
Commit this file. It carries no credential and cannot redirect one — there is no apiKey field and no apiUrl field, so a teammate cloning the repo picks up the project without picking up a secret, and a hostile edit cannot change where your token is sent.
A Zespan project has an id and a name, but no slug — so a bare ZESPAN_PROJECT_ID=2845c0ef-… tells a human nothing about which organization it belongs to. The link config stores the readable names beside the id for exactly that reason, and error messages print the names rather than the UUID. Re-running zespan link to change project keeps the environment already recorded in the file unless you pass a new --env.
The picker needs a terminal. Over a pipe or in CI, zespan link refuses before it makes any network call and names --project as the alternative, rather than blocking forever on input nobody will type:
A --project id your sign-in cannot reach writes nothing, and says so by id rather than leaving a config file naming a project that does not exist.

​
zespan projects list

Never prompts, so it is safe in CI and over a pipe.
--json prints the same data as { user, projects }, with id, name, orgSlug, orgName and role per project. It goes straight to stdout with no indentation or colour, so it pipes cleanly into jq. Only projects you can actually reach are listed — every organization you are a member of, and every project in it that has not been deleted. It is the same list the dashboard shows you.

​
Where the project id comes from

For zespan policy and any other command that needs a project, the resolution order is: --project flag → ZESPAN_PROJECT_ID → .zespan/config.json → .zespan.yaml zespan link outranks .zespan.yaml because it is the newer, explicit act (“link this directory to that project”). Nothing changes for existing projects, which have no .zespan/config.json until someone runs zespan link. The environment resolves the same way: --env → ZESPAN_ENVIRONMENT → .zespan/config.json → .zespan.yaml.
The API key and the API base URL are never read from either file — see CLI overview.

​
Next steps

zespan auth

Sign in first — both commands need a user session.

zespan policy

Plan and apply guardrail policies against the project you just linked.

CLI overview

Configuration precedence and the two credentials.

Environments

What --env targets, and how environment slugs resolve.