Sign in

Sign in once from your terminal, and every Spiral client on the same computer, including the CLI, the SDKs, and your own code while you develop it, uses that sign-in. The CLI caches your tokens and refreshes them before they expire, so you do not sign in again for each tool.

For pipelines and deployed services, do not use a personal sign-in. Give them a workload instead.

PrerequisitesCopy Anchor Link

• The spiraldb CLI is installed.
• You are a member of an Organization, or you have an invitation to one. See Manage members.

Sign inCopy Anchor Link

Run the login command:

spiral login

The CLI opens a verification page in your browser and shows a code. Check that the browser shows the same code, then approve the sign-in, and the command continues.

If you are a member of more than one Organization, the CLI asks you to select one. To select it in advance, pass --org:

spiral login --org org_01ABC

Pass --force to sign in again while the cached sign-in is still valid. You rarely need to run spiral login by hand: any command that needs a token starts the same sign-in when there is no usable one.

The CLI stores tokens in auth.json in the pyspiral folder of your user configuration directory (the folder keeps an older package name). On Linux, this is ~/.config/pyspiral/auth.json.

Verify your identityCopy Anchor Link

Show the signed-in principal, the active Organization, your role, and the token expiry:

spiral whoami

Pass --json for machine-readable output. For a workload identity, the command shows the workload ID instead of a user profile.

Over HTTP, read your own identity in the active Organization. This works for any signed-in member, but only with a user token; a workload token is rejected because a workload is not an Organization member.

curl https://api.spiraldb.dev/v1/organizations/me \
  -H "Authorization: Bearer $SPIRAL_TOKEN"

The response contains user_id, org_id, org_name, role, and email.

Choose an OrganizationCopy Anchor Link

A sign-in applies to one Organization at a time. List your memberships, then switch:

spiral orgs ls
spiral orgs switch org_01ABC

The switch gets new tokens for the selected Organization from your current sign-in, so you do not confirm a new code. Later commands use the new Organization.

The CLI does this over HTTP with its refresh token: it sends the refresh_token grant with an extra organization_id parameter. Only Spiral's own clients, such as the CLI and Studio, can switch this way. An Application gets its Organization when the user signs in to it.

curl -X POST https://auth.spiraldb.com/oauth/token \
  -d grant_type=refresh_token \
  -d client_id="$CLIENT_ID" \
  -d refresh_token="$REFRESH_TOKEN" \
  -d organization_id=org_01ABC

The response contains a new access_token for that Organization. The request fails if you are not a member of the Organization.

Get a token for HTTP callsCopy Anchor Link

The HTTP examples in this documentation read a bearer token from $SPIRAL_TOKEN. Print your sign-in's access token with --show-token; the token is the last line of the output:

export SPIRAL_TOKEN="$(spiral login --show-token | tail -n 1)"

curl https://api.spiraldb.dev/v1/organizations/me \
  -H "Authorization: Bearer $SPIRAL_TOKEN"

A user access token expires within an hour, so run the command again when it does. Do not store this token in a pipeline; use a workload there.

Sign outCopy Anchor Link

Remove the cached tokens from this computer:

spiral logout

The CLI also revokes the refresh token, so a copy of auth.json stops working too. The next command that needs a token starts a new sign-in.

Use a different authorization serverCopy Anchor Link

Every Spiral deployment uses the authorization server at https://auth.spiraldb.com. To use another one, for example on a local development setup, set SPIRAL_AUTH_URL to its URL.

TroubleshootingCopy Anchor Link

Where next: grant Project access, or create a Project.