Authenticate with Skytells CLI

Authentication methods

The CLI supports three authentication methods. Use device flow for interactive sessions, tokens for automation, and environment variables for CI/CD.

Device flow (recommended)

The default and most secure method. Uses OAuth 2.0 Device Authorization Grant (RFC 8628).

skytells login

What happens:

1. The CLI requests a device code from the Skytells API
2. A one-time code and URL appear in your terminal
3. Your browser opens the authorization page
4. Approve access in the browser
5. The CLI stores your token at ~/.config/skytells/credentials.json

Example output:

⠋ Initiating device authorization...

  Your device code is: ABCD-1234

  Open this URL in your browser to authorize:
  https://console.skytells.ai/device

  Waiting for authorization...
✔ Authenticated successfully!
  Credentials saved to ~/.config/skytells/credentials.json

The authorization window stays open for 15 minutes. If it expires, run skytells login again.

Request specific scopes

skytells login --scopes inference,projects.read,deployments.write

See the Token scopes table below for available values.

Personal access token

For non-interactive environments or quick setup with a pre-generated token:

skytells login --token

Paste your token when prompted. Tokens follow the format sk_pat_<64 hex characters>.

Create a token:

1. Go to console.skytells.ai/settings/tokens — or see Access Tokens in the Console docs
2. Click Create Token
3. Select the scopes you need
4. Copy the token — it is shown only once

Environment variables

For CI/CD pipelines and headless environments:

# User authentication
export SKYTELLS_TOKEN=sk_pat_your_token_here

# Project-scoped authentication
export SKYTELLS_ACCESS_KEY=sk_proj_your_key_here

Environment variables take precedence over stored credentials. See Configuration for the full precedence order.

Project access keys

Access keys scope CLI operations to a specific project. Commands for apps, databases, deployments, and environment variables all require a linked access key.

Link an access key

skytells link sk_proj_your_access_key

This stores the key alongside your user token. All project-scoped commands will use this key.

Where to find access keys

Access keys are in your project's settings:

1. Open console.skytells.ai — see Projects
2. Select your project → Settings
3. Copy the access key (sk_proj_*)

Token scopes

Scopes control what the CLI can access. Request the minimum scopes your workflow needs.

Default scopes (when no --scopes flag is used):

• inference
• projects.read
• deployments.read
• account.read

Managing credentials

Verify your session

skytells whoami

Displays your user ID, name, and authentication status.

Log out

skytells logout

Skip the confirmation prompt:

skytells logout --force

Credential file

Credentials are stored at:

~/.config/skytells/credentials.json

The file has 0600 permissions (owner read/write only). It contains your token, project access key, and a creation timestamp.

Override the storage location:

export SKYTELLS_CONFIG_DIR=/custom/path

Security

1. Use device flow for interactive sessions — avoids exposing tokens in shell history
2. Use environment variables in CI/CD — never store credentials in source code or config files
3. Request minimal scopes — only request permissions your workflow actually needs
4. Rotate tokens regularly — generate new ones at console.skytells.ai/settings/tokens and revoke old ones
5. Keep the CLI updated — npm update -g @skytells/cli

Troubleshooting auth

"You are not authenticated"

skytells login

Or set SKYTELLS_TOKEN in your environment.

"Access key required"

skytells link sk_proj_your_access_key

Or set SKYTELLS_ACCESS_KEY in your environment.

"Token is invalid or expired"

Generate a new token at console.skytells.ai/settings/tokens, then run skytells login.

"Insufficient scope"

Log in again with the required scopes:

skytells login --scopes inference,projects.read,projects.write,deployments.read,deployments.write

For more auth errors, see Troubleshooting.