Table of Contents

• Installation
• Quick Start
• Authentication
• Commands
  • Auth
  • Projects
  • Apps
  • Deployments
  • Drops
  • Models
  • Predictions
  • Databases
  • Environment Variables
  • Domains
  • Members
  • Status & Logs
  • Cloud Infrastructure
  • Orchestrator
  • Cognition
• Global Options
• Configuration
• Environment Variables
• Requirements
• Contributing
• License

Installation

Install the Skytells CLI globally using npm:

npm install -g @skytells/cli

Current release: 1.0.3.

Verify the installation:

skytells --version

You should see the installed CLI version printed to the terminal.

Update to the latest npm release:

skytells update

Quick Start

1. Sign in to your Skytells account:

skytells login

This opens your browser for secure authentication. You can also authenticate with a personal access token:

skytells login --token

Create a personal access token at console.skytells.ai/settings/tokens.

2. Link a project to your working directory:

skytells link <your-access-key>

Find your project access key at console.skytells.ai/projects/{project}/settings.

3. View your project:

skytells project

4. Deploy an app:

skytells deploy <app-id>

5. Stream logs in real time:

skytells logs <app-id> --follow

For detailed documentation, visit Skytells Learn.

Authentication

The Skytells CLI supports two authentication methods:

Device Flow (Recommended)

skytells login

This initiates a secure browser-based OAuth device flow. A code is displayed in your terminal — open the provided URL in your browser, enter the code, and authorize the CLI.

Personal Access Token

skytells login --token

You will be prompted to paste a personal access token. Create one at console.skytells.ai/settings/tokens.

Access Keys (Project-Scoped)

Access keys scope CLI operations to a specific project. Link an access key with:

skytells link <access-key>

Access keys use the format sk_proj_* and can be generated in your project settings at console.skytells.ai.

Skytells API Keys (Models and Predictions)

The Models and Predictions APIs use a separate Skytells API key. On first use, the CLI prompts for the key, validates it, and stores it securely. Create a key at console.skytells.ai/settings/api-keys.

skytells api-key set

Commands

Auth

skytells login

Authenticate with Skytells.

# Interactive browser-based login (recommended)
skytells login

# Login with a personal access token
skytells login --token

# Login with specific scopes
skytells login --scopes inference,projects.read,deployments.read,account.read

| Option | Description | |--------|-------------| | --token | Authenticate by pasting a personal access token | | --scopes <scopes> | Comma-separated scopes for device flow login |

Available scopes: inference, projects.read, projects.write, deployments.read, deployments.write, keys.read, keys.write, account.read

skytells logout

Remove stored credentials and log out.

skytells logout

# Skip confirmation prompt
skytells logout --force

| Option | Description | |--------|-------------| | -f, --force | Skip confirmation prompt |

skytells whoami

Display the currently authenticated user or linked project.

skytells whoami

# Output as JSON
skytells whoami --json

| Option | Description | |--------|-------------| | --json | Output as JSON |

skytells link <access-key>

Link a project access key to the CLI. This key scopes subsequent commands to the associated project.

skytells link sk_proj_abc123...

| Argument | Description | |----------|-------------| | access-key | A project-scoped access key (starts with sk_proj_) |

skytells api-key set

Authenticate or replace the API key used for Models and Predictions. The prompt masks the key and validates it before saving.

skytells api-key set
skytells api-key status
skytells api-key rm

skytells api-key update is an alias for set. The rm command also accepts remove and delete, plus --force to skip confirmation.

Projects

skytells projects ls

List all projects in your account.

skytells projects ls

# Filter by project type
skytells projects ls --type production

# Output as JSON
skytells projects ls --json

| Option | Description | |--------|-------------| | --type <type> | Filter projects by type | | --json | Output as JSON |

skytells projects add <name>

Create a new project.

skytells projects add my-project

# Specify project type
skytells projects add my-project --type production

| Argument | Description | |----------|-------------| | name | Name for the new project |

| Option | Description | |--------|-------------| | --type <type> | Project type | | --json | Output as JSON |

skytells project

View the currently linked project (requires access key).

skytells project

# Output as JSON
skytells project --json

skytells project set <field> <value>

Update a project setting.

skytells project set name "My New Project Name"
skytells project set description "Updated description"
skytells project set network_mode private

| Argument | Description | |----------|-------------| | field | Setting to update: name, description, network_mode | | value | New value for the setting |

| Option | Description | |--------|-------------| | --json | Output as JSON |

Apps

skytells apps ls

List all apps in the linked project.

skytells apps ls

# Output as JSON
skytells apps ls --json

skytells apps add <name>

Create a new app.

skytells apps add my-app

# Specify app type
skytells apps add my-app --type web

| Argument | Description | |----------|-------------| | name | Name for the new app |

| Option | Description | |--------|-------------| | --type <type> | App type | | --json | Output as JSON |

skytells apps inspect <id>

View detailed information about a specific app.

skytells apps inspect abc123

| Argument | Description | |----------|-------------| | id | App ID |

| Option | Description | |--------|-------------| | --json | Output as JSON |

skytells apps set <id> <field> <value>

Update an app setting.

skytells apps set abc123 name "Updated App Name"

| Argument | Description | |----------|-------------| | id | App ID | | field | Setting to update | | value | New value |

| Option | Description | |--------|-------------| | --json | Output as JSON |

skytells apps rm <id>

Delete an app.

skytells apps rm abc123

# Skip confirmation prompt
skytells apps rm abc123 --force

| Argument | Description | |----------|-------------| | id | App ID |

| Option | Description | |--------|-------------| | -f, --force | Skip confirmation prompt | | --json | Output as JSON |

skytells apps start <id>

Start a stopped app.

skytells apps start abc123

skytells apps stop <id>

Stop a running app.

skytells apps stop abc123

# Skip confirmation prompt
skytells apps stop abc123 --force

skytells apps restart <id>

Restart an app.

skytells apps restart abc123

skytells apps redeploy <id>

Trigger a redeployment of an app.

skytells apps redeploy abc123

All control commands (start, stop, restart, redeploy) support --force and --json options.

Deployments

skytells deploy <app>

Trigger a deployment for an app.

skytells deploy my-app

# Output as JSON
skytells deploy my-app --json

| Argument | Description | |----------|-------------| | app | App ID or slug |

| Option | Description | |--------|-------------| | --json | Output as JSON |

skytells deployments ls

List deployment history.

skytells deployments ls

# Filter by app
skytells deployments ls --app abc123

# Paginate results
skytells deployments ls --limit 10 --offset 20

# Output as JSON
skytells deployments ls --json

| Option | Description | |--------|-------------| | --app <id> | Filter deployments by app ID | | --limit <n> | Maximum number of results to return | | --offset <n> | Number of results to skip | | --json | Output as JSON |

Drops

skytells drops deploy <zip>

Upload a ZIP archive and deploy it as a static Drop.

skytells drops deploy ./dist/site.zip \
  --project 550e8400-e29b-41d4-a716-446655440000 \
  --slug product-docs

# Deploy a directory inside the archive and return JSON
skytells drops deploy ./dist/site.zip \
  --project 550e8400-e29b-41d4-a716-446655440000 \
  --slug product-docs \
  --build-path dist \
  --name "Product Docs" \
  --json

| Argument | Description | |----------|-------------| | zip | Path to a ZIP archive whose filename ends in .zip |

| Option | Description | |--------|-------------| | --project <uuid> | Project UUID (required) | | --slug <slug> | Unique 2-63 character Drop slug (required) | | --build-path <path> | Build path inside the archive; defaults to the archive root | | --upload-id <uuid> | Correlation UUID; generated automatically when omitted | | --name <name> | Display name, up to 100 characters | | --json | Output as JSON |

The resulting site is available at https://<slug>.drops.skytells.app. See the Drops guide for authentication, plan limits, and CI usage.

Models

skytells models ls

List models available to your Skytells API key.

skytells models ls
skytells models ls --type image
skytells models ls --json

skytells models inspect <slug>

Show model metadata, pricing, capabilities, and optional input/output JSON Schemas.

skytells models inspect truefusion
skytells models inspect truefusion --schemas --json

Predictions

skytells predictions create <model>

Generate an image, video, or audio asset using a model namespace from skytells models ls.

# Prompt shortcut
skytells predictions create truefusion \
  --prompt "A portrait of an astronaut in a garden" \
  --wait

# Model-specific JSON input and immediate asset download
skytells predictions create truefusion \
  --input '{"prompt":"A lighthouse at dusk","aspect_ratio":"16:9"}' \
  --output ./generated

# Load complex input from a file
skytells predictions create beatfusion-2.0 \
  --input @audio-input.json \
  --wait \
  --json

| Option | Description | |--------|-------------| | --input <json-or-file> | Model-specific JSON object or @path/to/input.json | | --prompt <text> | Shortcut for an input containing only prompt | | --webhook <url> | Webhook URL for prediction events | | --wait | Poll until the prediction reaches a terminal state | | --timeout <seconds> | Maximum wait time; defaults to 900 seconds | | --output <directory> | Wait and download generated assets immediately | | --json | Output as JSON |

Provide exactly one of --input or --prompt. Use skytells models inspect <slug> --schemas to discover each model's accepted input fields.

Manage predictions

skytells predictions ls
skytells predictions get <id>
skytells predictions cancel <id>
skytells predictions rm <id>

Generated output URLs expire five minutes after completion. Use --output <directory> when creating a prediction to wait for completion and download the files immediately. See the Predictions guide for filters, JSON inputs, CI usage, and lifecycle details.

Databases

skytells databases ls

List all databases in the linked project.

skytells databases ls

# Output as JSON
skytells databases ls --json

skytells databases add <name> <type>

Create a new database.

# Create a PostgreSQL database
skytells databases add my-db postgres

# Create a Redis database
skytells databases add cache redis

# Create with additional options
skytells databases add my-db postgres \
  --description "Production database" \
  --password mypassword \
  --db-name app_db \
  --db-user app_user

| Argument | Description | |----------|-------------| | name | Database name | | type | Database engine: postgres, mysql, mariadb, mongo, redis |

| Option | Description | |--------|-------------| | --docker-image <image> | Custom Docker image | | --description <desc> | Database description | | --password <pass> | Database password | | --db-name <name> | Database name within the engine | | --db-user <user> | Database user | | --json | Output as JSON |

skytells databases inspect <id>

View detailed information about a database.

skytells databases inspect abc123

| Argument | Description | |----------|-------------| | id | Database ID |

| Option | Description | |--------|-------------| | --json | Output as JSON |

skytells databases set <id> <field> <value>

Update a database setting.

skytells databases set abc123 name "Renamed DB"
skytells databases set abc123 backup_enabled true
skytells databases set abc123 backup_schedule "0 2 * * *"
skytells databases set abc123 external_port 5432

| Argument | Description | |----------|-------------| | id | Database ID | | field | Setting to update: name, description, backup_enabled, backup_schedule, external_port | | value | New value |

| Option | Description | |--------|-------------| | --json | Output as JSON |

skytells databases rm <id>

Delete a database.

skytells databases rm abc123

# Skip confirmation
skytells databases rm abc123 --force

skytells databases start <id>

Start a stopped database.

skytells databases start abc123

skytells databases stop <id>

Stop a running database.

skytells databases stop abc123

skytells databases deploy <id>

Deploy a database.

skytells databases deploy abc123

All database control commands support --force and --json options.

Environment Variables

skytells env ls

List environment variables.

# List project-level variables
skytells env ls

# List variables for a specific app
skytells env ls --app abc123

# Output as JSON
skytells env ls --json

| Option | Description | |--------|-------------| | --app <id> | Scope to a specific app | | --json | Output as JSON |

skytells env set <pairs...>

Set one or more environment variables using KEY=value format.

# Set a single variable
skytells env set DATABASE_URL=postgres://...

# Set multiple variables at once
skytells env set API_KEY=abc123 NODE_ENV=production PORT=3000

# Set for a specific app
skytells env set --app abc123 SECRET_KEY=mykey

| Argument | Description | |----------|-------------| | pairs | One or more KEY=value pairs |

| Option | Description | |--------|-------------| | --app <id> | Scope to a specific app | | --json | Output as JSON |

Domains

skytells domains ls

List custom domains.

skytells domains ls

# Output as JSON
skytells domains ls --json

skytells domains add <domain>

Add a custom domain.

skytells domains add example.com

# Assign to a specific app
skytells domains add example.com --app abc123

| Argument | Description | |----------|-------------| | domain | The domain name to add |

| Option | Description | |--------|-------------| | --app <id> | Associate with a specific app | | --json | Output as JSON |

skytells domains rm <id>

Remove a custom domain.

skytells domains rm domain-id

# Skip confirmation
skytells domains rm domain-id --force

| Argument | Description | |----------|-------------| | id | Domain ID |

| Option | Description | |--------|-------------| | -f, --force | Skip confirmation prompt | | --json | Output as JSON |

Members

skytells members ls

List team members of the linked project.

skytells members ls

# Output as JSON
skytells members ls --json

| Option | Description | |--------|-------------| | --json | Output as JSON |

Status & Logs

skytells status

View the status overview of the linked project and its apps.

skytells status

# Output as JSON
skytells status --json

| Option | Description | |--------|-------------| | --json | Output as JSON |

skytells logs <app>

Stream real-time logs from an app.

# View recent logs
skytells logs my-app

# Follow logs in real time (streaming)
skytells logs my-app --follow

# View deployment logs
skytells logs my-app --type deployment

# Show last 50 lines
skytells logs my-app --tail 50

# Logs for a specific deployment
skytells logs my-app --deployment dep-id

| Argument | Description | |----------|-------------| | app | App ID or slug |

| Option | Description | |--------|-------------| | --type <type> | Log type: container (default), deployment | | --deployment <id> | Filter by deployment ID | | --tail <n> | Number of recent log lines to show | | --follow | Stream logs in real time (SSE) | | --json | Output as JSON |

Cloud Infrastructure

Skytells operates a globally distributed GPU infrastructure. Explore available plans and regions at skytells.ai/infrastructure. For edge computing, see skytells.ai/edge.

skytells cloud ls

List all cloud instances.

skytells cloud ls

# Output as JSON
skytells cloud ls --json

skytells cloud deploy

Deploy a new cloud instance.

skytells cloud deploy \
  --region ewr \
  --plan vc2-1c-1gb \
  --os 387 \
  --label "my-server" \
  --hostname "my-server"

GPU instances (H100 / A100):

# Deploy an NVIDIA H100 instance
skytells cloud deploy \
  --region ewr \
  --plan gpu-h100-1 \
  --os 387 \
  --label "h100-training"

# Deploy an NVIDIA A100 instance
skytells cloud deploy \
  --region lax \
  --plan gpu-a100-1 \
  --os 387 \
  --label "a100-inference"

| Option | Description | |--------|-------------| | --region <region> | Deployment region | | --plan <plan> | Instance plan/size | | --os <id> | Operating system ID | | --label <label> | Instance label | | --hostname <name> | Instance hostname | | --tags <tags> | Comma-separated tags | | --firewall-group <id> | Firewall group ID | | --vpc <id> | VPC ID | | --ipv6 | Enable IPv6 | | --json | Output as JSON |

skytells cloud inspect <id>

View detailed information about a cloud instance.

skytells cloud inspect instance-id

| Argument | Description | |----------|-------------| | id | Instance ID |

| Option | Description | |--------|-------------| | --json | Output as JSON |

skytells cloud destroy <id>

Destroy a cloud instance.

skytells cloud destroy instance-id

# Skip confirmation
skytells cloud destroy instance-id --force

| Argument | Description | |----------|-------------| | id | Instance ID |

| Option | Description | |--------|-------------| | -f, --force | Skip confirmation prompt | | --json | Output as JSON |

skytells cloud start <id>

Start a halted cloud instance.

skytells cloud start instance-id

skytells cloud halt <id>

Halt (stop) a running cloud instance.

skytells cloud halt instance-id

skytells cloud reboot <id>

Reboot a cloud instance.

skytells cloud reboot instance-id

All cloud control commands support --force and --json options.

Orchestrator

skytells workflows ls

List all orchestrator workflows.

skytells workflows ls

# Output as JSON
skytells workflows ls --json

| Option | Description | |--------|-------------| | --json | Output as JSON |

skytells orchestrator overview

View orchestrator overview, stats, and health.

skytells orchestrator overview

# Output as JSON
skytells orchestrator overview --json

Learn more about Orchestrator at orchestrator.skytells.ai.

skytells orchestrator executions

List workflow executions.

skytells orchestrator executions

# Filter by workflow
skytells orchestrator executions --workflow wf-id

# Filter by status
skytells orchestrator executions --status completed

# Paginate
skytells orchestrator executions --limit 20 --offset 0

| Option | Description | |--------|-------------| | --workflow <id> | Filter by workflow ID | | --status <status> | Filter by execution status | | --limit <n> | Maximum number of results | | --offset <n> | Number of results to skip | | --json | Output as JSON |

skytells orchestrator inspect <id>

View details and logs for a specific execution.

skytells orchestrator inspect exec-id

| Argument | Description | |----------|-------------| | id | Execution ID |

| Option | Description | |--------|-------------| | --json | Output as JSON |

skytells orchestrator metrics

View execution metrics over a time period.

skytells orchestrator metrics

# Specify date range
skytells orchestrator metrics --from 2026-01-01 --to 2026-01-31

| Option | Description | |--------|-------------| | --from <date> | Start date (ISO format) | | --to <date> | End date (ISO format) | | --json | Output as JSON |

skytells orchestrator usage

View resource usage statistics.

skytells orchestrator usage

# Specify date range
skytells orchestrator usage --from 2026-01-01 --to 2026-01-31

| Option | Description | |--------|-------------| | --from <date> | Start date (ISO format) | | --to <date> | End date (ISO format) | | --json | Output as JSON |

Cognition

Cognition provides observability, monitoring, error tracking, and security insights for your applications.

skytells cognition overview

View a high-level overview of application health and observability.

skytells cognition overview

# Specify project and time window
skytells cognition overview --project proj-id --hours 24

| Option | Description | |--------|-------------| | --project <id> | Project ID | | --hours <n> | Time window in hours | | --json | Output as JSON |

skytells cognition errors

List application errors.

skytells cognition errors

# Paginate results
skytells cognition errors --limit 20 --offset 0

| Option | Description | |--------|-------------| | --project <id> | Project ID | | --limit <n> | Maximum number of results | | --offset <n> | Number of results to skip | | --json | Output as JSON |

skytells cognition security

List security events and alerts.

skytells cognition security

| Option | Description | |--------|-------------| | --project <id> | Project ID | | --limit <n> | Maximum number of results | | --offset <n> | Number of results to skip | | --json | Output as JSON |

skytells cognition runtime

View runtime performance snapshots.

skytells cognition runtime

| Option | Description | |--------|-------------| | --project <id> | Project ID | | --limit <n> | Maximum number of results | | --offset <n> | Number of results to skip | | --json | Output as JSON |

skytells cognition anomalies

List detected anomalies.

skytells cognition anomalies

| Option | Description | |--------|-------------| | --project <id> | Project ID | | --limit <n> | Maximum number of results | | --offset <n> | Number of results to skip | | --json | Output as JSON |

skytells cognition events

List real-time events with polling support.

skytells cognition events

# Fetch events after a specific event ID
skytells cognition events --since event-id

| Option | Description | |--------|-------------| | --project <id> | Project ID | | --limit <n> | Maximum number of results | | --since <id> | Fetch events after this event ID | | --json | Output as JSON |

skytells cognition timeseries

View time-series metrics data.

skytells cognition timeseries

# Specify time window
skytells cognition timeseries --hours 48

| Option | Description | |--------|-------------| | --project <id> | Project ID | | --hours <n> | Time window in hours | | --json | Output as JSON |

Global Options

These options are available on all commands:

| Option | Description | |--------|-------------| | -v, --version | Display the CLI version | | -h, --help | Display help for a command | | --json | Output results as JSON (available on most commands) |

Configuration

Credentials

Credentials are stored securely at:

~/.config/skytells/credentials.json

The file is created with restrictive permissions (0600) and contains your authentication token and/or project access key.

Custom Config Directory

Override the default config directory:

export SKYTELLS_CONFIG_DIR=/path/to/config

Environment Variables

| Variable | Description | |----------|-------------| | SKYTELLS_API_URL | Override the API base URL | | SKYTELLS_TOKEN | Override the stored authentication token | | SKYTELLS_ACCESS_KEY | Override the stored project access key | | SKYTELLS_API_KEY | API key for Models and Predictions | | SKYTELLS_AI_API_URL | Override the Models and Predictions API base URL | | SKYTELLS_CONFIG_DIR | Override the config directory path |

Requirements

• Node.js >= 18.0.0
• A Skytells account

Useful Links

• Documentation
• Console
• GPU Infrastructure & Regions
• Edge Computing
• Create a Project
• API Keys
• Personal Access Tokens
• Orchestrator
• Status Page

Contributing

We welcome contributions. Please read our contributing guidelines before submitting a pull request.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m "feat: add my feature")
4. Push to the branch (git push origin feature/my-feature)
5. Open a pull request

License

This project is licensed under the MIT License.