Skytells CLI

The official command-line interface for the Skytells platform.
Manage projects, apps, databases, cloud infrastructure, and more — directly from your terminal.

Documentation • Installation • Quick Start • Commands • Changelog • Security

Installation

Install the Skytells CLI globally using npm:

npm install -g @skytells/cli

Verify the installation:

skytells --version

You should see 1.0.0 printed to the terminal.

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.

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_`)

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

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_CONFIG_DIR`	Override the config directory path

Requirements

Node.js >= 18.0.0
A Skytells account

Useful Links

Contributing

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

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

License

This project is licensed under the MIT License.

Built with precision by Skytells

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
assets		assets
bin		bin
docs		docs
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Folders and files

Latest commit

History

Repository files navigation

Skytells CLI

Table of Contents

Installation

Quick Start

Authentication

Device Flow (Recommended)

Personal Access Token

Access Keys (Project-Scoped)

Commands

Auth

skytells login

skytells logout

skytells whoami

skytells link <access-key>

Projects

skytells projects ls

skytells projects add <name>

skytells project

skytells project set <field> <value>

Apps

skytells apps ls

skytells apps add <name>

skytells apps inspect <id>

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

skytells apps rm <id>

skytells apps start <id>

skytells apps stop <id>

skytells apps restart <id>

skytells apps redeploy <id>

Deployments

skytells deploy <app>

skytells deployments ls

Databases

skytells databases ls

skytells databases add <name> <type>

skytells databases inspect <id>

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

skytells databases rm <id>

skytells databases start <id>

skytells databases stop <id>

skytells databases deploy <id>

Environment Variables

skytells env ls

skytells env set <pairs...>

Domains

skytells domains ls

skytells domains add <domain>

skytells domains rm <id>

Members

skytells members ls

Status & Logs

skytells status

skytells logs <app>

Cloud Infrastructure

skytells cloud ls

skytells cloud deploy

skytells cloud inspect <id>

skytells cloud destroy <id>

skytells cloud start <id>

skytells cloud halt <id>

skytells cloud reboot <id>

Orchestrator

skytells workflows ls

skytells orchestrator overview

skytells orchestrator executions

skytells orchestrator inspect <id>

skytells orchestrator metrics

skytells orchestrator usage

Cognition

skytells cognition overview

skytells cognition errors

skytells cognition security

skytells cognition runtime

skytells cognition anomalies

skytells cognition events

skytells cognition timeseries

`skytells login`

`skytells logout`

`skytells whoami`

`skytells link <access-key>`

`skytells projects ls`

`skytells projects add <name>`

`skytells project`

`skytells project set <field> <value>`

`skytells apps ls`

`skytells apps add <name>`

`skytells apps inspect <id>`

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

`skytells apps rm <id>`

`skytells apps start <id>`

`skytells apps stop <id>`

`skytells apps restart <id>`

`skytells apps redeploy <id>`

`skytells deploy <app>`

`skytells deployments ls`

`skytells databases ls`

`skytells databases add <name> <type>`

`skytells databases inspect <id>`

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

`skytells databases rm <id>`

`skytells databases start <id>`

`skytells databases stop <id>`

`skytells databases deploy <id>`

`skytells env ls`

`skytells env set <pairs...>`

`skytells domains ls`

`skytells domains add <domain>`

`skytells domains rm <id>`

`skytells members ls`

`skytells status`

`skytells logs <app>`

`skytells cloud ls`

`skytells cloud deploy`

`skytells cloud inspect <id>`

`skytells cloud destroy <id>`

`skytells cloud start <id>`

`skytells cloud halt <id>`

`skytells cloud reboot <id>`

`skytells workflows ls`

`skytells orchestrator overview`

`skytells orchestrator executions`

`skytells orchestrator inspect <id>`

`skytells orchestrator metrics`

`skytells orchestrator usage`

`skytells cognition overview`

`skytells cognition errors`

`skytells cognition security`

`skytells cognition runtime`

`skytells cognition anomalies`

`skytells cognition events`

`skytells cognition timeseries`

Packages