CLI Troubleshooting

Authentication errors

"You are not authenticated"

No valid token is stored and SKYTELLS_TOKEN is not set.

skytells login

Or set the environment variable:

export SKYTELLS_TOKEN=sk_pat_your_token_here

"Access key required"

The command requires a project-scoped access key.

skytells link sk_proj_your_access_key

Or set the environment variable:

export SKYTELLS_ACCESS_KEY=sk_proj_your_access_key

Find your access key in project settings at console.skytells.ai.

"Token is invalid or expired"

Your stored token was revoked or expired.

1. Generate a new token at console.skytells.ai/settings/tokens — see Access Tokens
2. Re-authenticate:

skytells login

"Insufficient scope"

Your token does not include the permissions the command requires.

Log in again with the needed scopes:

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

See Token scopes for the full list.

Device flow times out

The browser authorization was not completed within 15 minutes.

Run skytells login again and approve in the browser promptly.

Installation errors

"Command not found: skytells"

The CLI is not installed or not in your PATH.

npm install -g @skytells/cli

Verify:

which skytells
skytells --version

If you use nvm or another Node.js version manager, ensure the right version is active before installing:

nvm use 20
npm install -g @skytells/cli

"Node.js version not supported"

The CLI requires Node.js 18 or later.

node --version

Upgrade using nvm:

nvm install 20
nvm use 20

Or via Homebrew on macOS:

brew install node@20

Permission error on install (Linux/macOS)

Do not use sudo npm install -g. Instead, configure a user-owned npm prefix:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @skytells/cli

Command errors

Command hangs or produces no output

Likely a network connectivity issue or API unavailability.

1. Check your internet connection
2. Verify access to the Skytells API:

curl -s https://console.skytells.ai/api/v1/health

3. Check status.skytells.ai for service incidents

Failed deployment

If skytells deploy completes but the deployment fails:

# Check deployment logs
skytells logs <app> --type deployment

# Review environment variables
skytells env ls --app <app-id>

# Inspect the app configuration
skytells apps inspect <app-id>

# Fix issues and redeploy
skytells apps redeploy <app-id>

Network errors

Connection refused or timeout

A firewall, proxy, or VPN is blocking the connection.

1. Ensure https://console.skytells.ai is reachable from your network
2. If behind a corporate proxy, configure it:

export HTTPS_PROXY=http://proxy.example.com:8080

3. Confirm outbound HTTPS (port 443) is allowed

SSL certificate errors

Your system clock is incorrect, or a corporate proxy is intercepting HTTPS.

1. Verify your system clock is accurate
2. If a proxy performs TLS inspection, configure the corporate CA:

export NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.crt

Getting help

Quick diagnostic capture:

# CLI version
skytells --version

# Authentication state (no secrets printed)
skytells whoami --json 2>&1 | jq '{authenticated: (. != null), error: null}' \
  || echo "Not authenticated"

# Project link status
skytells project --json 2>&1 | jq '.id // "No project linked"'

# App health summary
skytells status --json 2>&1

# Network connectivity
curl -s -o /dev/null -w "%{http_code}" https://console.skytells.ai/api/v1/health

If you cannot resolve an issue:

# Show usage for any command
skytells <command> --help

• Check the online documentation
• Search existing issues or open a new one at github.com/skytells/cli