Signing in
The browser device flow, where the token is stored, and how to authenticate on a machine that has no keyring.
Signing in
shortspan login- 1
The CLI asks for a device code
It receives a short user code to display and a longer device code to poll with. Both expire after ten minutes.
- 2
You approve it in a browser
The CLI prints a URL on shortspan.dev. Open it in a browser where you are already signed in, check that the code shown matches the one in your terminal, and approve.
- 3
The CLI collects the token
It has been polling every five seconds. Once you approve, it receives an API token, stores it, and records the device.
- 4
Context is pre-selected where it can be
If you belong to exactly one organization it becomes active, and if that organization has exactly one project so does that. Otherwise you are told to choose.
Where the token is stored
In your operating system keyring, keyed by API host - never in a file:
| Platform | Store |
|---|---|
macOS | Keychain |
Linux | Secret Service (GNOME Keyring, KWallet) |
Windows | Credential Manager |
Keying by host means signing into a self-hosted deployment does not overwrite your hosted token. Switching api_host switches which token is used, with no need to sign in again.
Machines with no keyring
A CI runner has no Keychain, no D-Bus, and nobody to open a browser. Since injecting secrets into exactly those environments is a large part of what this tool is for, the environment overrides are a requirement rather than a convenience.
| Variable | Effect |
|---|---|
| Supplies the token directly, bypassing the keyring entirely. |
| Overrides the configured host for a single invocation. |
| Suppresses the background update notice. |
- name: Deploy
env:
SHORTSPAN_TOKEN: ${{ secrets.SHORTSPAN_TOKEN }}
SHORTSPAN_NO_UPDATE_CHECK: '1'
run: |
shortspan org use acme
shortspan project use production
shortspan run api-production -- ./deploy.shMint the token in the console under API tokens, or with shortspan token create, and scope it to only what the job needs. A deploy job that reads secrets does not need secrets:write.
Token abilities
Every token carries a set of abilities. shortspan login mints one with the standard interactive set; a token created by hand can be narrower.
| Ability | Grants | Default |
|---|---|---|
| List secrets and inject them into processes | yes |
| Print a secret value to the terminal | no |
| Create, update, and delete secrets | no |
| Open SSH sessions and run commands on servers | yes |
| Obtain database credentials | yes |
| Inject AWS credentials | yes |
| Obtain kubeconfigs | yes |
| Run runbooks | yes |
| Create and edit runbooks | no |
| Approve a runbook execution | no |
| Request temporary access | yes |
| Approve and deny access requests | no |
| Read the audit log | no |
An ability never grants more than your role does. A viewer holding a token with secrets:reveal still cannot reveal anything: abilities narrow, they do not elevate.
Signing out and revoking
shortspan logoutIf you have lost the machine, do not rely on being able to run logout on it. Revoke the device or the token from the console instead - see API tokens and devices. Revocation takes effect on the next request; there is no cached grace period.
When sign-in fails
- not authenticated. Run 'shortspan login' first
No token for the current host. Check
shortspan config get api_host- signing in against the wrong host is the usual cause.- authorization_pending
Normal. The CLI is still waiting for you to approve in the browser, and will keep polling until the ten-minute window closes.
- 403 account_suspended
The account or its workspace has been suspended. This is not an expired credential and signing in again will not help; contact whoever administers the workspace.
- 426 Upgrade Required
Either the connection was not TLS, or this CLI version has been withdrawn. Run
shortspan upgrade, which works even while blocked.
Something here wrong or missing? Tell us.