Command reference
Every weave command, grouped by area — authentication, nodes, models, keys, and runtime.
Every weave command, grouped by area. This mirrors weave help; run
weave <command> --help for the authoritative, always-current flag list.
Most commands accept --json to emit machine-readable output instead of a table —
handy for scripting and agents.
Global options
These flags and environment variables apply to every command:
| Flag | Env | Purpose |
|---|---|---|
--org <id> |
WEAVE_ORG |
Organization (object id or name) for operator commands. Defaults to your saved default organization (weave orgs use), then your sole compute-owning organization. |
--endpoint <url> |
WEAVE_ENDPOINT |
Control-plane base URL. Defaults to the build's baked endpoint. |
--hub <url> |
WEAVE_HUB |
Explicit gRPC hub override, such as https://platform.openinfer.io:8443. Rarely needed — the control plane advertises the hub at pair/connect. |
--config <path> |
WEAVE_CONFIG |
Bootstrap config file. Defaults to ~/.weave/weave.toml. |
--identity <path> |
WEAVE_IDENTITY |
Identity file (node id + pairing token). Defaults to ~/.weave/runner.toml. |
--name <name> |
WEAVE_NODE_NAME |
Friendly display name for this node, sent to the hub and saved to weave.toml. |
--engine-url <url> |
WEAVE_ENGINE_URL |
Local runtime base URL. Defaults to http://127.0.0.1:1337. |
Authentication
Log in and manage credentials.
weave auth login # device-code sign-in, then stores credentials locally
weave auth status # show stored credentials
weave auth logout # remove stored credentials
weave auth login prints a URL and a one-time code. Approve it in a browser on any
machine, so it works over SSH and on headless boxes. If a local browser is available it
opens for you. It accepts --endpoint <url> to authenticate against a specific control
plane (defaults to $WEAVE_ENDPOINT).
Pairing & serving
Join a machine to the fleet and serve.
weave pair <weave_pt_…> # store the durable pairing token locally, then exit
weave up # pair if needed, launch/supervise oi-runtime, connect, serve
weave run # connect and reconnect forever (identity must already exist)
weave pair [token]stores the pairing (refresh) token and exits — no connection is opened. The token may come from the argument or$WEAVE_PAIR_TOKEN; if omitted and you are logged in, one is minted for your organization automatically.weave up [token]is the idempotent entrypoint for unattended/fleet use: pair if there's no identity yet, then run. A bareweave upsupervises the local runtime so it's a full serving node. It stops the runtime cleanly onSIGTERM, so it works as a container entrypoint. Pass--no-managed-enginewhen an external supervisor (systemd'soi-runtime.service, or a separate runtime container) owns the runtime.weave runexchanges the stored pairing token for an access token, connects, and reconnects forever.
Nodes & fleet
Inspect and operate connected nodes.
weave nodes # list the organization's nodes and their loaded models
weave node <id> # inspect one node
weave node <id> --enable-routing # start routing requests to this node
weave node <id> --disable-routing # drain: stop routing new requests
weave fleet # cluster-wide health: nodes, GPU memory, sessions
weave fleet reapply # re-push the organization's committed-topology layout
weave fleet plan --model @oi/Qwen3.5-397B-A17B:44 --model @oi/Qwen3.5-27B:8 # device-level plan (dry run)
weave fleet plan --model @oi/Qwen3.5-27B:8:32768 --apply # plan + push (guard-checked)
An organization on the oi-plan planner is driven with its own verbs, which ask the hub the same questions the Fleet planner page does and are refused for the same callers:
weave fleet status # source, active run, roll-out (paused? why), waves, recent events
weave fleet plan # plan the organization's saved intent as a new run
weave fleet runs [--limit 10] # the runs, newest first; the active one is marked
weave fleet activate <run> # move the organization onto a planned run (re-activating an earlier run is the undo)
weave fleet pause # no wave starts until resume
weave fleet resume [--accept-floor-gap]
weave fleet waves stop # incident switch: stop every organization's waves (admin organization only)
weave fleet waves start
plan, activate, pause and resume need the owner or admin role in the organization.
plan and activate wait up to 20 seconds for the hub to answer: a plan or activation check
that takes longer says so and goes on, and weave fleet runs / weave fleet status show its
outcome. waves stop / start need an admin of the OpenInfer admin organization (--org
names it). The stop switch is fleet-wide and each hub applies it within
30 seconds. weave fleet plan --model ... and weave fleet reapply are layout commands: the
hub refuses them for an organization on oi-plan. A hub that predates a verb says
"this hub doesn't support weave fleet <verb> yet".
weave fleet plan takes --model SLUG:DEMAND[:CONTEXT] (repeatable): DEMAND is
concurrent sessions and CONTEXT is tokens per session, defaulting to the model's catalog
average. --place-by sessions|weight picks the packing strategy (default sessions). It
is a dry run until you pass --apply, and the hub refuses a layout that fails its
overcommit guard.
Logs — bounded query by default, live tail with --follow:
weave logs <id> --tail 50 # last 50 lines
weave logs <id> --since 10m --grep cuda # last 10m, filter for "cuda"
weave logs <id> --since 10m --until 5m # time window
weave logs <id> --service runtime --follow # live tail the runtime logs
weave logs <id> --follow --since 5m # backfill 5m, then follow
weave logs <id> --component core --level warn # runtime's structured trace buffer (warn+)
Services to tail are runtime, agent, system (comma-separated or repeat
--service; omit for all). --component reads the runtime's structured trace buffer
(core, scheduler, session, transfer, http) — a bounded snapshot that can't
be combined with --follow. Service logs come from journald, so a containerized node
only serves the --component buffer (see
Deploying with containers).
Restart an in-place service (no download, no version change) — the remedy for a wedged runtime. Waits for recovery and exits non-zero if it doesn't come back:
weave restart <id> # restart oi-runtime, wait
weave restart <id> --agent # restart the weave agent instead
weave restart <id> --drain-grace 30 # let in-flight requests finish first
weave restart <id> --reason "oom" # recorded in the node's logs
weave restart <id> --no-wait # fire and forget
Upgrade to the latest published build — the agent downloads, verifies, drains, swaps, restarts, re-warms, and rolls back if the new build doesn't come up:
weave upgrade <id> # upgrade the weave agent (default)
weave upgrade <id> --runtime # upgrade oi-runtime instead
weave upgrade <id> --no-wait # return once the agent accepts
"Latest" means the runtime build this Studio currently serves for the node's
platform and accelerator. A node never upgrades on its own. It moves only when you
run weave upgrade <id> --runtime or use Upgrade on the node's page in Studio,
which appears while the node runs a different build. The node page also shows which
runtime build the node runs.
On a containerized node an upgrade lands in the container's filesystem only, so it is lost when the container is recreated. Rebuild the image instead (see Deploying with containers).
Models & routing
Manage the catalog and where models run.
weave models # list the organization's model catalog
weave models available # platform models the organization can import
weave models available --fits <node-id> # only those that fit that node's GPU + RAM
weave models import @oi/Qwen3.5-9B # import + publish (owner/admin; re-import is a no-op)
weave route @oi/Qwen3.5-27B # routing state for a model: candidates, health, inflight, ownership
Push a desired model set to a node. The hub requires at least one high-priority model in the set:
weave push <id> --high @oi/Llama-3.2-1B-Instruct --wait
weave push <id> --high @oi/A --medium @oi/B --low @oi/C
--high/--medium/--lowset priority; repeat each for multiple models.--modeladds a model with no explicit priority (the hub treats it as medium).--tier <name>(e.g.hot).--waitpolls until each model reacheshot;--timeout <secs>(default 120) bounds the wait and exits non-zero on timeout.
Keys & tokens
Three distinct credential types — don't mix them up:
pk_…inference API keys —Authorization: Beareragainst/v1.usr_…operator CLI tokens — yourweave auth loginsessions.weave_pt_…pairing tokens — reusable, organization-scoped credentials a machine presents toweave pair/weave up.
weave keys mint # mint an inference API key (pk_…), printed once
weave keys mint --name ci # label the key (default "weave CLI")
weave tokens ls # list your CLI tokens
weave tokens revoke <id> # revoke a CLI token
weave pairing-tokens ls # list the organization's live pairing tokens (no secrets)
weave pairing-tokens mint --label ci # mint a weave_pt_… (printed once)
weave pairing-tokens revoke <id> # revoke; nodes on it must re-pair
Every mint prints its secret once — capture it immediately.
Organizations
weave whoami # show the authenticated compute-owning organization
weave orgs ls # list the organizations you belong to
weave orgs use <organization> # set the default organization for operator commands
API keys, pairing tokens, and nodes all belong to the organization. Switch organizations
with weave orgs use, or pass --org to a single command.
Runtime
Install or update the local oi-runtime inference runtime using the pairing token this node
already holds (or $WEAVE_TOKEN) — so a box with just the public CLI can become a
full serving node without re-running the install script.
weave runtime install # auto-detect cpu/cuda and install
weave runtime install --accel cuda # force the CUDA build
weave runtime install --force # reinstall even if a runtime is present
Auto-detection picks cuda when nvidia-smi finds a GPU and cpu otherwise. Pass
--accel explicitly when installing where no GPU is visible, such as a docker build.