Subsystem

subroutine token

The 3 commands under subroutine token, each with its arguments and options.

subroutine token [OPTIONS] COMMAND [ARGS]...

Issue credentials for agents and other machines.

subroutine token create

subroutine token create [OPTIONS]

Issue a token, and print it once.

Examples:

subroutine token create --title "My laptop"

subroutine token create --username thomas --title "Thomas's laptop"

subroutine token create --service-account claude --scope task:read --scope task:write

subroutine token create --service-account claude --workspace projects --project WEB

subroutine token create --title "Acme, this month" --expires now+30d

Named on its own it is yours. '--username' issues for somebody who already has an account; '--service-account' issues for a machine identity and creates one if there is none. They are separate flags because they are separate decisions: naming a person under '--service-account' is refused rather than quietly handing out their credential.

Neither will issue for an account that could not use it. A deactivated account is turned down here, rather than given a token that fails the first time it is presented.

'--expires' names a whole day and the credential works through the end of it, the same reading a deadline gets. A token that stopped at midnight starting the day somebody named is the kind of surprise that arrives at the worst moment.

The secret is readable exactly once, here. Nothing recovers it afterwards, including this program: what is stored is a hash. It is never passed as an argument to anything, because that would put it in 'ps' output and shell history.

'--scope' and '--project' narrow different things and are both worth saying for an agent. A scope decides which *verbs* the credential carries; a project decides which *items* it can reach at all, and it brings everything underneath that project with it. Giving an agent one project and nothing else is what makes it a bounded worker rather than a trusted one.

'--profile' names a scenario instead, and expands into exactly those flags: 'worker' for an agent that owns one project, 'collaborator' to read several and write one, 'observer' to report on work and change nothing, 'colleague' for a second person in one workspace. It refuses a combination that means two things at once rather than picking one.

'--store' is opt-in rather than the default, and that is a deliberate choice. Writing a narrow token into credentials.toml under the local connection would silently narrow your own CLI to whatever the agent was given — a token that quietly takes authority away is worse than one you have to paste somewhere.

With '--service-account' it is stored as that connection's agent instead, which is the one case where the paragraph above does not apply: an agent's token is resolved only by a process an agent started, so it narrows nothing of yours.

Options

subroutine token list

subroutine token list [OPTIONS]

Show the credentials this instance has issued.

Examples:

subroutine token list

Prefixes, never secrets. Only a hash is stored, so there is nothing here to leak — and the prefix is what 'token revoke' takes, which is the point of printing it.

Each credential says what it can reach and when it was last used, so "which of these can write?" and "is this one still in use?" are answerable here rather than by reading the database. A credential narrowed to nothing in particular says so in one word.

subroutine token revoke

subroutine token revoke [OPTIONS] [prefix]

Stop a credential working, now.

Examples:

subroutine token revoke sr_a1b2c3d4

Immediate. A revoked credential is checked on every request rather than cached, so there is no session to wait out — which is what makes this the answer when a token has leaked or a piece of work has ended.

Arguments