CLI

The blade CLI

blade is the command-line entry point to the platform — *"run Python functions on the GPU fleet"*. It is a grouped command tree: a handful of top-level commands (run, serve, deploy, logs, status, runs, cancel, nodes, setup, shell) plus sub-command groups (token, app, volume, secret, image, sandbox, cron, queue, dict, map). Invoking any group or the bare bladekit with no arguments prints its help.

Every command that reaches the control plane resolves credentials the same way: the token and API URL come from ~/.blade/config.toml, overridden by the FABRIC_TOKEN and FABRIC_API_URL environment variables. If no token is configured the command exits with code 2 and prints a hint to run blade token set or set FABRIC_TOKEN. Errors from the control plane are rendered with their machine code and human message (exit 1); usage errors exit 2; a Ctrl-C cancellation exits 130.

blade setup · authentication

blade setup authenticates this machine through the browser and saves an API token — like modal setup. It opens your browser to confirm your identity, mints a token bound to your workspace, and writes it to ~/.blade/config.toml. It long-polls for up to 5 minutes; if the window closes without confirmation it exits with code 1 and asks you to re-run.

blade setup

--api-url str

Control plane base URL to authenticate against. Defaults to the configured value / FABRIC_API_URL. The confirmed URL is persisted alongside the token.

If a token was minted elsewhere, register it directly with blade token set instead. The token is never accepted as a positional argument — that would leak it into ps aux, shell history and process monitors — so it is read from --from-env or from stdin. blade token show prints the effective token (masked) and endpoint, and where each value came from.

blade token set --from-env FABRIC_TOKEN

echo $TOKEN | blade token set

blade run

Execute a script's @app.local_entrypoint and stream its logs live. The entrypoint runs locally; any .remote() / .map() calls it makes are dispatched to the fleet, and this process follows the first opened run's logs until it finishes. On success, hot containers are drained promptly. Ctrl-C cancels the remote run(s); if the node is unreachable the run sits in cancelling and the CLI prints *"cancellation pending on node"*.

blade run train.py

script Path

Python script defining the app and its @app.local_entrypoint (positional, required).

--no-logs boolDefault: False

Do not stream logs — just run and report the outcome.

blade serve

The development loop. blade serve runs the entrypoint, watches your files, and hot-reloads the bundle in under ~5 seconds on every save. The run is created with serve=true so its container never drains on idle: edit a file and the bundle is re-pushed (deduplicated by sha256) and the code reloads while the loaded model stays hot. Ctrl-C stops it.

blade serve app.py

script Path

Python script defining the app (positional, required).

blade deploy

Create a versioned deployment from an app's @app.web_endpoint() / @app.asgi_app() surfaces (and any schedule= cron functions). The script must define exactly one bladekit.app; zero or more than one is an error. Each deploy creates (or reuses) the app, publishes a new immutable deployment version, and prints the app URL and every endpoint's methods, path and kind.

blade deploy api.py --label env=prod --label team=ml

script Path

Python script defining the app (positional, required).

--label str

Deployment label as KEY=VALUE, repeatable. An entry without = or with an empty key is rejected with exit code 2.

blade app · manage deployments

Lifecycle commands for deployed apps. Every command accepts either an app name or an app_… id; a name is resolved to its id, raising APP_NOT_FOUND if unknown.

blade app rollback my-api --version 3

blade app scale

Update a deployed endpoint's autoscaling bounds live, with no redeploy — only the flags you pass change, and the autoscaler applies the new bounds within seconds. If the app has one endpoint it is chosen automatically; with several, pass --endpoint. You must pass at least one flag, otherwise the command exits 2 with *"Nothing to change."*

blade app scale my-api --min 2 --max 8 --reserved 2

app_name_or_id str

App name or app_… id (positional, required).

--endpoint, -e str

Endpoint name to scale. Defaults to the only endpoint if there is exactly one.

--min int

Minimum replicas (0–50).

--max int

Maximum replicas (1–50).

--concurrency int

Max concurrent inputs per replica (1–100).

--idle int

Scale-down idle seconds (30–3600).

--reserved int

Hybrid: replicas kept always-on on non-interruptible capacity; the rest burst on the endpoint's class.

--target int

Autoscaling v2: per-replica concurrency the autoscaler aims for (1–100, <= --concurrency).

--buffer int

Autoscaling v2: warm spare replicas kept while active (0–10; 0 removes the buffer).

--vllm-waiting int

vLLM preset: target requests waiting in vLLM's queue per replica (1–1000; 0 removes it; web-server endpoints only).

--clear-policy boolDefault: False

Clear the scaling policy entirely, back to default concurrency autoscaling.

Runs: logs · status · runs · cancel · nodes

Inspect and control runs after they start, and view fleet capacity.

blade logs run_01hxyz --follow

blade runs --state pending --state running --limit 100

blade volume

Manage network volumes from the shell. Every command accepts a volume name or a vol_… id (an unknown name raises VOLUME_NOT_FOUND). Uploads and downloads use presigned URLs; put creates a new content-addressed generation.

blade volume put weights model.safetensors /ckpt/model.safetensors

blade secret

Manage secrets. Values are read from --from-env or from stdin — never from a positional argument, which would leak them into ps and shell history. list and the delete confirmation only ever show names and env-key names, never values.

blade secret set hf --from-env HF_TOKEN

printf 'API_KEY=sk-...\nORG=acme\n' | blade secret set openai

blade image

Inspect the image catalogue and your DSL builds. The logs command is where the actionable hint on a failed bladekit.Image build points.

blade image logs ibld_01hxyz --follow

blade shell · blade sandbox

blade shell opens an interactive shell inside a GPU sandbox — equivalent to Sandbox.create(...) then exec /bin/bash (or a command you pass). It streams stdin/stdout/stderr over the sandbox exec WebSocket and terminates the sandbox on exit. Use -- to separate a command from the flags.

blade shell --gpu RTX-A4500 -- python3 script.py

--image, -i strDefault: "fabric/base"

Image alias or ref for the sandbox.

--gpu, -g str

GPU type, e.g. RTX-A4500. Omit for a CPU sandbox.

--runtime strDefault: "runsc"

Sandbox runtime: runsc (gVisor, default) or runc (trusted-only debug).

--timeout intDefault: 3600

Sandbox lifetime in seconds.

--block-network flagDefault: off

Give the sandbox no network at all: loopback only, no DNS, no Internet. The shell, file I/O and tunnels still work; anything the code inside reaches for does not.

cmd list[str]

Command to run (positional, after --). Defaults to /bin/bash.

The blade sandbox group inspects long-lived sandboxes created programmatically: blade sandbox list [--state S] [--limit N] lists them (states creating / running / terminating / terminated / failed; --limit defaults to 50, 1–200), and blade sandbox terminate <sandbox_id> tears one down (SIGTERM → grace → SIGKILL).

blade sandbox terminate sb_01hxyz

cron · queue · dict · map

Small inspection groups for the primitives. Cron history is retained on the server; queue and dict commands operate on named distributed stores; map follows batch invocations.

blade dict set config timeout 30

blade map results map_01hxyz --order arrival --return-exceptions

Related reference