CLI Configuration

Environment variables, credential storage, JSON output, and configuration precedence for the Skytells CLI.

Environment variables

All environment variables the CLI recognizes:

Variable	Description	Default
`SKYTELLS_TOKEN`	Personal access token for authentication	—
`SKYTELLS_ACCESS_KEY`	Project-scoped access key	—
`SKYTELLS_API_URL`	Override the API base URL	`https://console.skytells.ai`
`SKYTELLS_CONFIG_DIR`	Custom path for configuration files	`~/.config/skytells`

Environment variables take precedence over stored credentials. See Precedence order below.

Credential storage

Default location

~/.config/skytells/credentials.json

Override the location

export SKYTELLS_CONFIG_DIR=/custom/path

File structure

{
  "token": "sk_pat_...",
  "access_key": "sk_proj_...",
  "created_at": "2026-04-13T10:30:00.000Z"
}

File permissions

The credentials file is created with 0600 permissions (owner read/write only). Do not change these permissions.

Never commit ~/.config/skytells/credentials.json to version control. In CI/CD environments, use environment variables instead.

JSON output

Every command supports --json for machine-readable output. This enables scripting, piping to jq, and CI/CD integration.

# Get project as JSON
skytells project --json

# Parse app names with jq
skytells apps ls --json | jq '.[].name'

# Use app status in a script
APP_STATUS=$(skytells status --json | jq -r '.apps[0].status')

# Get latest deployment status
skytells deployments ls --limit 1 --json | jq -r '.[0].status'

jq quick reference

Common patterns for processing CLI JSON output:

# All running app IDs
skytells apps ls --json | jq -r '.[] | select(.status == "running") | .id'

# App count by status
skytells apps ls --json | jq 'group_by(.status) | map({status: .[0].status, count: length})'

# Latest deployment succeeded?
skytells deployments ls --app <id> --limit 1 --json | jq -r '.[0].status == "success"'

# Extract database host and port
skytells databases inspect <id> --json | jq '{host: .host, port: .port}'

# All env variable keys in project scope
skytells env ls --json | jq -r '.[] | select(.scope == "project") | .key'

# Cognition error types and counts
skytells cognition errors --limit 100 --json | jq 'group_by(.type) | map({type: .[0].type, count: length}) | sort_by(-.count)'

# Cloud instance IDs and GPU type
skytells cloud ls --json | jq -r '.[] | "\(.id)\t\(.gpu // "cpu")\t\(.status)"'

Precedence order

When multiple configuration sources are present, the CLI applies this order (highest to lowest):

Command-line flags — --token, --scopes, etc.
Environment variables — SKYTELLS_TOKEN, SKYTELLS_ACCESS_KEY
Stored credentials — ~/.config/skytells/credentials.json

CI/CD configuration

Use environment variables in your pipeline. Do not pass tokens as command-line arguments or store them in files.

GitHub Actions:

env:
  SKYTELLS_TOKEN: ${{ secrets.SKYTELLS_TOKEN }}
  SKYTELLS_ACCESS_KEY: ${{ secrets.SKYTELLS_ACCESS_KEY }}

GitLab CI:

variables:
  SKYTELLS_TOKEN: $CI_SKYTELLS_TOKEN
  SKYTELLS_ACCESS_KEY: $CI_SKYTELLS_ACCESS_KEY

Shell:

export SKYTELLS_TOKEN=sk_pat_your_token_here
export SKYTELLS_ACCESS_KEY=sk_proj_your_key_here

skytells deploy my-api

For a complete CI/CD integration guide, see Advanced Usage.

How is this guide?

On this page