Configuration and scope

The CLI takes configuration from four places. This page says exactly which one wins, and what each is for.

Scope resolution

Every secret-touching command needs an (organisation, project, environment) triple. It is resolved in this order, first answer winning:

1. --project / --environment flags — explicit beats everything.
2. .xecret.yaml, discovered by walking up from the working directory, the way git finds .git. So xecret run works from any subdirectory.
3. The service token's pinned scope, when XECRET_TOKEN is set.
4. Nothing — an error telling you to run xecret init.

The organisation is never one of these. It always comes from the credential: a login is pinned to one organisation, a service token to one organisation, project and environment.

.xecret.yaml

Written by xecret init, read by everything else.

project: checkout-api
environment: development

Two slugs, and that is the entire file. The type that models it has exactly two fields, so nothing in the CLI can serialise anything else into it — which is what makes the file safe to commit.

Commit it. It is what makes git clone && xecret run -- npm run dev work for a new teammate without a setup document.

Per-developer overrides

The file names the default environment, usually development. Anyone who needs a different one passes a flag rather than editing the committed file:

xecret run --environment staging -- npm run dev

Or, if you always want a different default, set it for your shell session:

export XECRET_ENVIRONMENT=staging   # not read by the CLI — see below

That variable does not exist, deliberately. An environment variable that silently redirects which secrets a command loads is exactly the mechanism by which someone runs a migration against production believing it was staging. Be explicit with the flag.

Environment variables

XECRET_TOKEN in practice

export XECRET_TOKEN=xst_live_…
export XECRET_API_URL=https://secrets.your-company.com   # self-hosted only
xecret run -- npm run build

While XECRET_TOKEN is set:

• xecret login, logout and init are refused — none of them make sense for a credential you did not create on this machine.
• No offline cache is written or read. A CI runner is disposable; an encrypted cache file on it would be a liability with no benefit.
• whoami reports the token's pinned scope rather than a person.

Where credentials are stored

The credential from xecret login goes into your operating system's keychain:

Where no keyring is available — a bare container, a headless server, a minimal window manager — the CLI falls back to a 0600 file under ~/.xecret/ and tells you on stderr that it has done so. It never falls back silently: you should know when your credential moved from a keychain to a file.

Force the file store with XECRET_KEYRING=file. That is occasionally the right answer on a headless build machine where the keyring prompts for a password nobody can type.

Files the CLI creates

xecret cache clear removes the cache; xecret logout removes both the cache and the credential.

Pointing at a self-hosted deployment

# once, interactively
xecret login --api-url https://secrets.your-company.com

# in CI, where there is no stored login
export XECRET_API_URL=https://secrets.your-company.com
export XECRET_TOKEN=xst_…

The compiled-in default is https://xecret.playxoft.com. See self-hosting.

Next

• The offline cache — what the cache does and does not do.
• Command reference — every flag in one page.
• Secrets in CI — the token-based setup end to end.