Skip to content

CLI

sky is the command-line client for the Skyward control plane. Every command talks to a daemon: the CLI owns no state and hosts no control plane of its own.

Installation

Install the CLI separately from the SDK:

pip install "skyward[cli]"

The CLI needs a daemon to talk to. To run one on this machine, install both extras:

pip install "skyward[cli,server]"

The other optional extras are tui for the terminal UI, notebook for the Jupyter provisioner, storage for S3-compatible storage, and client for remote HTTP access from the SDK. Provider-specific extras are not required.

Daemon resolution

Commands resolve the daemon in this order:

  1. --url;
  2. SKYWARD_URL;
  3. http://127.0.0.1:17590, where sky server start binds.

So the usual local session is sky server start once, then every command as it comes — no flag, no environment variable. A command that reaches nothing says so and exits non-zero rather than starting a control plane of its own:

$ sky compute list
no daemon at http://127.0.0.1:17590 — run: sky server start

sky config show shows the effective resolution and where it came from.

Commands that render rows accept --output table or --output json. The default is table; use JSON for scripts.

sky version

sky version

sky server

sky server manages a local daemon process. The detached process writes its PID to ~/.skyward/server.pid and its output to ~/.skyward/server.log.

sky server start
sky server start --host 0.0.0.0 --port 8080
sky server start --foreground
sky server stop
sky server restart
sky server status
sky server status --url http://host:17590
sky server interface set tailscale0

start waits for /v1/health/live. The address it prints also serves the browser console, at /, when the package carries a built one (task web:build in a checkout). --foreground keeps the daemon attached to the terminal and does not create a PID file. stop only stops a process started by this CLI. restart is stop then start, and starts one even when there was nothing to stop; the machines are unaffected, since they belong to the daemon rather than to the process.

interface set records, in ~/.skyward/server.interface, a network interface every daemon started on this machine listens on beside its --host: a name (en0, tailscale0), one of this machine's IPv4 addresses, or 0.0.0.0 for all of them. A name is read for its IPv4 addresses each time a daemon starts. The loopback address stays, so local pools and commands need no --url. The daemon already running is not restarted; sky server restart applies the change. If the interface has no address when the daemon starts, the daemon listens on its host alone and start says so. The API has no authentication, so anything that reaches the interface can create computes and open shells on them.

sky compute

Create

create registers the provider account from the current process and submits a compute. It returns without waiting for the compute to become ready.

sky compute create --provider aws
sky compute create --provider aws --accelerator A100 --nodes 4 --region us-east-1
sky compute create --provider runpod --accelerator RTX_4090 --name research
sky compute create --provider runpod --accelerator RTX_4090 --pip "tilelang[nvcc]" --apt build-essential --plugin torch

The supported provider kinds are:

aws, container, gcp, hyperstack, jarvislabs, lambda, massed_compute, novita, runpod, salad, scaleway, tensordock, vastai, verda, and vultr.

A kind whose SDK extra is not installed is not registered, so it will not appear. sky providers list --kinds shows what this installation can actually reach.

The available create flags are --provider, --name, --accelerator, --nodes, --region, --cpus, --memory, --ttl, --base, --python, --pip, --apt, --pip-index, --env, --mutable, --plugin, --url, and --output. --mutable is Image(mutable=True): the packages and includes may be changed afterwards with update. The provider account reads credentials from the current process. Credential values are not printed by the CLI.

--base, --python, --pip, --apt, --pip-index and --env are the image the nodes build, with the meaning sky.Image gives them in the SDK: the packages land in the interpreter run and exec use. --pip, --apt, --pip-index, --env and --plugin repeat for more than one; --env takes KEY=VALUE. --plugin names a plugin by its kind (torch, jax, huggingface, …), with parameters as key=value after a colon: --plugin torch:backend=gloo,cuda=cu124. The parameters are validated against the plugin's own fields before anything is sent, the way constructing sky.plugins.Torch(...) would, and a parameter left out is the plugin's default. sky compute view shows the image a compute was asked to build.

sky new is an alias for sky compute create:

sky new --provider container --name local

Scale

scale changes how many machines a compute stands on, without replacing the ones already up:

sky compute scale research --nodes 8
sky compute scale research --nodes 2:8

--nodes N is a fixed size; --nodes MIN:MAX is an elastic range, the same thing nodes=(2, 8) means in the SDK. The bounds are written whole, so the flag is the compute's new size and not a patch on the old one.

Like create, it returns without waiting: what comes back is a new generation, and the machines are bought or drained by reconciliation afterwards. A compute running a collective plugin (torch, jax, accelerate) is refused — its process group was formed with the ranks it started with, and one added now would block in it.

Update

update changes the image of a compute that is up, without replacing its machines. It takes the mutable fields of the image (--pip, --pip-index, --include, --exclude) and works only on a compute created with a mutable image:

sky compute update research --pip six
sky compute update research --include ./src/classy_enc

The flags give the image's new lists, so a package left out of the command is not in the next image. Like scale, it returns without waiting: the nodes refresh afterwards, each one passing through node.bootstrapping and back to node.ready. A compute whose image is fixed refuses it with image_fixed.

Read and delete

sky compute list
sky compute list --history 20
sky compute list --state ready
sky compute get research
sky compute get research --output json
sky compute view research
sky compute delete research

list is newest first, and it is two questions rather than one: every compute that is still live, then the newest --history finished ones (5 by default, 0 for none). A compute's row outlives its machines, so without that bound the deleted ones are all the list would eventually be. --state asks for one state instead, and is then the whole filtered list.

get and view accept a compute id or name. view also prints the node rows. delete is an intent change: the returned state can remain deleting while the daemon reconciles the provider state.

Files and commands

These commands use the daemon's file and execution endpoints:

sky compute ls research /data
sky compute rm research /tmp/output
sky compute upload research ./data.csv /data/data.csv
sky compute download research /data/result.json ./result.json
sky compute exec research --node 0 nvidia-smi
sky compute run research train.py
sky compute run research train.py --node all

ls, rm, and upload target every node by default where the command allows it. download reads one node and defaults to rank 0. exec runs a shell command on the selected nodes. run sends a local Python script through the worker path; --node places it: any (the default, one node with a slot free), all, or a rank.

sky log

sky log replays a compute's recorded events. Without --follow, it stops after the replay is quiet.

sky log research
sky log research --follow
sky log research --limit 50 --output json
sky log research --idle 3
sky log export research history.jsonl
sky log export research history.md

export accepts .jsonl, .json, .md, and .markdown destinations.

sky offers

Offers are served from the daemon's provider cache. list sorts by the cheapest available price and supports:

sky offers list
sky offers list --accelerator H100 --min-count 4 --min-vram 80 --limit 10
sky offers list --provider runpod --max-price 2.5
sky offers list --refresh --output json

The filters are --provider, --accelerator, --min-count, --min-vram, --max-price, --limit, and --refresh. --provider accepts an account id or name. --accelerator accepts the provider's spelling; returned offers use the shared normalized accelerator vocabulary. --limit 0 prints all rows.

fetch forces a refresh and reports the number of cached rows per provider:

sky offers fetch
sky offers fetch --provider vastai

summary groups cached rows by accelerator and provider:

sky offers summary
sky offers summary --accelerator A100 --refresh

Each provider has its own freshness interval. If a refresh fails, the daemon keeps the provider's stale rows and records the error on the provider account.

sky providers

A provider is a registered account, not only a provider kind. The daemon uses the account credentials; list and check responses do not return them.

sky providers list
sky providers list --kinds
sky providers set runpod --config cloud_type=community
sky providers set aws --name production --config region=eu-west-1
sky providers check
sky providers check production

list shows registered accounts. list --kinds shows supported kinds, required credential fields, and offer-cache TTLs. check reports the last recorded result; it does not perform a new credential probe.

set registers an account, or rewrites the settings of one already registered. --config takes the account's own fields as key=value, repeatable, and they are validated against the account before anything is sent. Credentials are never written here: they are read from the environment, the same way a pool reads them. The row is what the daemon builds its adapter from, so a compute created with --provider runpod provisions with whatever set last wrote.

sky config

Skyward has no configuration file. These commands show the resolved daemon URL, and the database a daemon started here would use:

sky config path
sky config show
sky config validate

validate checks /v1/health/ready and exits non-zero when the daemon is not reachable or not ready.

Top-level compute aliases

The following commands are shortcuts for common compute operations:

sky status
sky status research
sky sessions
sky stop research

status lists all computes when no reference is supplied and reads one compute otherwise. sessions lists all computes. stop delegates to compute deletion.

Interactive commands

sky compute ssh research
sky compute ssh research --node 0
sky compute ssh research --node 0 --command "nvidia-smi"
sky repl research

ssh opens a shell on one machine. No key is involved on this side: the SSH connection belongs to the daemon, which generated the compute's key and never hands it out, and what crosses is the terminal's bytes. sky console is the same command under its older top-level name.

--node is a rank; without one it takes the lowest rank the daemon has a link to. A machine takes a session as soon as it answers SSH, which is the whole of its bootstrap before it is ready — so this is also how you watch one install its driver, or find out why it never finished. One that is still booting is waited for rather than refused.

repl opens the Python interpreter bootstrapped on that machine.

sky monitor attaches to a running compute and follows it until you interrupt:

sky monitor research
sky monitor research --mode log

--mode rich (the default) draws the live footer; --mode log prints plain lines, which is what you want in CI or when piping to a file. Monitoring creates nothing — the compute has to exist already.

Next steps