Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Authenticate without putting tokens in command arguments or plaintext profile files.

​
Prerequisites

  • An active StackShift account
  • Access to the account authorization page

​
Workflow

1
Authorize the active profile with the browser/device flow.
2
Confirm the active identity.
3
Use an environment, stdin, or protected token file only for CI.
4
Revoke credentials when they are no longer needed.

​
Interactive login

  • The CLI prints the verification URL and user code.
  • Without --no-browser, it also tries to open the complete verification URL.
  • The code expires and can be exchanged only once.
  • The CLI waits using the server-provided polling interval and honors cancellation.

​
Where credentials are stored

Interactive tokens are stored under the stackshift-cli service in the operating-system credential manager, keyed by profile name. The YAML profile file contains only the API URL and optional default project, application, and environment. There is no plaintext credential fallback. If the credential manager cannot store a token, login fails instead of writing it to configuration.

​
CI token inputs and precedence

For an individual command, token lookup uses this order: STACKSHIFT_TOKEN, --token-file, --token-stdin, then the active profile credential.
  • On Unix, a token file must not be accessible by group or other users; mode 0600 works.
  • A token is never accepted as a positional argument.
  • --token-stdin reads one trimmed line and reuses it within that process.

​
Revoke and remove credentials

Normal logout finds and revokes the active API token before deleting the local credential. --local-only removes only the local credential and leaves the server token active.

​
Expected result

Interactive credentials live in the operating-system credential manager, not the profile file.

​
Common failures

  • The device code expired or authorization was denied.
  • The active token lacks the customer CLI read/write scope required by the operation.
  • A Unix token file has group or other permission bits.
  • The credential manager is unavailable in a headless session.

Profiles, defaults, and global options

Use profiles for API and resource defaults, then override them explicitly for one command.

Output, pagination, errors, and automation

Select stable machine output, fetch paginated results, and handle documented exit codes.

Diagnostics, completion, and troubleshooting

Check version compatibility, produce sanitized diagnostics, install completion, and resolve common failures.