supi is SuperPipeline from a terminal; superpipeline is the same program under its full name. These pages are generated from the table the CLI’s own supi help is printed from, so the two cannot disagree. For a guided tour rather than a reference, see From the terminal.
The verb comes first. Flags may be written --name value or --name=value, anywhere after the verb, before or after the positional arguments. A value that itself starts with -- must use the = form.
A person signs in once with supi login. It finds the server’s sign-in service from the server itself (/.well-known/oauth-protected-resource) — for app.superpipeline.dev that is https://accounts.superjackfruit.com, the same account you use in the web app — and runs its device flow: open the printed link, confirm the code, and supi keeps a device credential of its own. Every command after that exchanges it for a token that lives minutes, without a browser.
The credential a command acts with is the first of these that exists:
$SUPERPIPELINE_AGENT_TOKEN_FILE — an agent; the file is re-read on every run
$SUPERPIPELINE_AGENT_TOKEN — an agent
$SUPERPIPELINE_TOKEN — a person’s token, used exactly as supplied
$AGENTPOD_TOKEN — a person’s hub token, used exactly as supplied
supi login’s cached token, while it is fresh
supi login’s device credential, exchanged at the sign-in service recorded at login
the token AgentPod’s fleet login cached — skipped when it was issued for a different audience, which is the case once a server has moved to the sign-in service
fleet login’s device credential — exchanged at the sign-in service it recorded for this server’s audience (and cached in supi’s own directory, never in fleet’s), or, for a server not yet on the sign-in service, renewed at the hub it recorded
Steps 7 and 8 exist so a machine already signed in with fleet login needs no second sign-in. Environment tokens are never renewed and never silently swapped for a file on disk: when one expires, replace or unset it. An agent credential is never renewed either, and a person’s token in an agent slot (or an spa_ token in a person’s slot) is refused rather than used.
Credentials live under the platform config directory — $XDG_CONFIG_HOME (or ~/.config) on Linux, ~/Library/Application Support on macOS, %APPDATA% on Windows — in superpipeline/device.json and superpipeline/token.json for supi login, and superpipeline/fleet-token.json for a token exchanged from fleet’s device. They are written atomically with mode 0600. A device credential is sent only to the service it was issued by, over HTTPS (plain HTTP only on loopback), with redirects disabled.
a FILE holding an agent credential, re-read on every run. Outranks every other credential. Named but missing or empty is a refusal, never a fall-back to somebody else’s credential
SUPERPIPELINE_AGENT_TOKEN
supi
an agent credential: an spa_… token, or an agent JWT. A person’s token here is refused by its kind
SUPERPIPELINE_TOKEN
supi
a person’s token, used as supplied: never renewed, never replaced. An spa_ token here is refused — it belongs in SUPERPIPELINE_AGENT_TOKEN
AGENTPOD_TOKEN
supi
a person’s AgentPod hub token, used as supplied. Only a server still verifying hub tokens accepts it; app.superpipeline.dev refuses it, so do not export it into a shell that runs supi — it outranks supi login and every command would answer 401
SUPERPIPELINE_URL
supi
the SuperPipeline server to talk to. Default https://app.superpipeline.dev. It changes where commands go and which audience a token is requested for, never where a device credential is sent
XDG_CONFIG_HOME
supi
Linux: the config directory credentials live under (default ~/.config)
APPDATA
supi
Windows: the config directory credentials live under
BIN_DIR
the installer
where the installer puts supi and superpipeline (default ~/.local/bin)
VERSION
the installer
a release tag for the installer to pin, instead of the latest
SKILL_DIR
the installer
where the installer also places the agent skill (by running supi skill install --dir); unset, no skill is installed
supi adds no authority and checks no permission itself: the server decides, and a refusal is printed as it arrives. Each command’s page lists what the server asks for, two ways:
A person needs a workspace role: viewer < member < admin < owner, each including the ones before it. See People and roles.
An agent token needs a scope — read, queue, plan or compose for a coordinator. An spa_ token reads and plans; only an agent JWT (a station token) carries the dispatch grant that queues work. Deciding a gate is refused to every agent token. See Authentication.
0 when the command did what it says; 1 for everything else — a usage error, a missing or expired credential, a refusal, a server error, a network failure. The message goes to standard error, followed by a hint where there is one. Output goes to standard output, so --json output can be piped safely.
401 means sign in: supi login.
403 means your role or your token’s scopes do not permit this. The two are never conflated, because telling somebody to sign in again when the answer is “you may not” sends them round a loop.
