Installing the SDK
The client is bladekit, published on public PyPI — no extra index, no token. It installs the blade command and the bladekit Python module.
pip install bladekitblade setup
The primary way to authenticate a machine. Opens a browser to confirm your identity, mints an API token bound to your workspace, and writes it to ~/.blade/config.toml — the same shape as modal setup. Under the hood it POSTs /v1/token-flow/start, prints the confirmation URL, then long-polls GET /v1/token-flow/{flow_id}/wait (each call blocks server-side for up to ~20s) until the flow reports status: "confirmed" with a token, or a 5-minute deadline is reached.
blade setup [--api-url URL]--api-urlstrDefault:NoneControl plane base URL to authenticate against. Falls back to the currently configured value (file or
FABRIC_API_URL), and to the public control planehttps://cp.run.blade.shwhen nothing is configured — so a fresh install can just runblade setup. On success this becomes the persistedapi_url.
blade setup --api-url https://cp.run.blade.shblade token set / blade token show
Lower-level, non-interactive alternative to the browser flow — write or inspect the config file directly. Useful in CI or headless environments where blade setup can't open a browser. The token is never accepted as a positional argument (that would leak it into ps aux and shell history): pass --from-env or pipe it on stdin.
blade token set [--api-url URL] [--from-env VAR]--api-urlstrDefault:NoneControl plane base URL to persist alongside the token.
--from-envstrDefault:NoneName of a local environment variable to read the token from (e.g.
FABRIC_TOKEN). If omitted, the token is read from stdin instead — one line, not echoed when run interactively.
blade token set --from-env FABRIC_TOKENecho $TOKEN | blade token setblade token show prints the effective api_url and a masked token, plus where each came from — env (FABRIC_API_URL), file (~/.blade/config.toml), default, or (for the token) runner (inside an AI Fabric container) / none. The token is masked as its first 6 and last 4 characters (abc123…wxyz), or just set if it's 12 characters or shorter.
blade token showConfig file: ~/.blade/config.toml
Both blade setup and blade token set write to the same TOML file, which every client reads at startup. The writer is intentionally minimal — it only ever serializes two keys, merging with whatever is already on disk (setting just the token leaves an existing api_url untouched).
| Key | Description |
|---|---|
api_url | Control plane base URL, trailing slash stripped. |
token | The API token minted by blade setup or set by blade token set. |
Environment variables & precedence
Every client resolves config in the same order: environment variables win over the config file, which wins over built-in defaults.
| Variable | Effect |
|---|---|
FABRIC_API_URL | Overrides the configured api_url. If unset and the file has none either, defaults to the public control plane, https://cp.run.blade.sh. |
FABRIC_TOKEN | Overrides the configured token. Takes priority over both the config file and the in-container runner credentials. |
FABRIC_RUNNER_TOKEN | The run's ephemeral token. It is read by the runner (PID 1) at boot and removed from the environment before your code is imported — your function and its subprocesses never see it. Inside a container the SDK obtains it from the runner in-process instead (blade token show reports the source as runner), checked only if neither FABRIC_TOKEN nor a file token is set, so a function calling back into the AI Fabric API (Sandbox.create without secrets, Queue/Dict items) authenticates as the run's owner without its own token. The control plane accepts that token only on that small set of endpoints — never to attach secrets to a sandbox, create or list volumes, or list org resources — and only while the run is alive. |
FABRIC_CONFIG | Overrides the config file's path (default ~/.blade/config.toml). Mainly for tests / isolated environments. |
Pointing at a different control plane
To switch which control plane the CLI and SDK talk to, either persist it (blade setup --api-url, or blade token set --api-url to change it without redoing the browser flow) or override it per-shell/per-command with FABRIC_API_URL — the environment variable always wins over whatever is saved on disk.
blade setup --api-url https://cp.run.blade.shFABRIC_API_URL=https://cp.run.stg.blade.sh blade token showReference from the Blade console · Updated .