Supervaizer CLI

Created: 2025-08-06 Updated: 2026-10-04

pip install supervaizer               # core
pip install "supervaizer[deploy]"     # adds the deploy commands (quote the brackets in zsh)

supervaizer --help
supervaizer --version                 # -v; the CLI also checks PyPI and prints a notice when a newer release exists

scaffold

Creates supervaizer_control.py (the controller definition) and supervaize_instructions.html (agent setup instructions) in the current directory.

The control file is a minimal Supervaizer v2 agent: one registration, one job.start surface, and one job.start action. Run supervaizer start --local to try it before you connect Studio.

supervaizer scaffold                          # both files
supervaizer scaffold --output-path my_ctl.py  # custom control file path (env: SUPERVAIZER_OUTPUT_PATH)
supervaizer scaffold --force                  # overwrite existing files (env: SUPERVAIZER_FORCE_INSTALL=true)
supervaizer scaffold instructions             # only the instructions page (--control-file, --output-path, --force)
supervaizer scaffold refresh-instructions     # regenerate the instructions page from the control file

supervaizer login [--api-url URL] [--env-file .env] [--no-browser]

Logs you in to Supervaize Studio with no key to copy. The command prints an approval page and a short code, and opens the page in your browser. On the page you sign in or sign up (Google included), check that the code is the same, choose the workspace and approve. The command then receives a new developer API key and writes these variables to the environment file: SUPERVAIZE_API_KEY, SUPERVAIZE_WORKSPACE_ID, SUPERVAIZE_API_URL, SUPERVAIZER_WORKSPACE_AUTH_REQUIRED, SUPERVAIZER_WORKSPACE_AUTH_ISSUER and SUPERVAIZER_WORKSPACE_AUTH_JWKS_URL.

Option	Env var	Default	Notes
`--api-url`	`SUPERVAIZE_API_URL`	`https://app.supervaize.com`	Address of the Studio API
`--env-file`	none	`.env`	Other lines of the file stay as they are. A new file is readable by its owner only. A file named `.envrc` gets `export` lines
`--browser` / `--no-browser`	none	on	With `--no-browser`, open the printed page yourself, on any device

The command prints the names of the variables, never a value. Keep the environment file out of git. The code is valid for 15 minutes and for one login. A denied or expired code writes nothing. A Studio that does not have this login answers with a clear error; create the key on Studio's Developer page in that case.

The full sequence from an empty project to an agent in Studio:

supervaizer scaffold                                   # or your own control file
supervaizer login                                      # browser approval, writes .env
supervaizer start --env-file .env --public-url https://your-controller.example.com

The start log then shows the Studio page of each registered agent. Open it: a workspace admin sets the agent's workspace reference and accepts the workspace authorization there. This is the only step in Studio. See 2026_05_WORKSPACE_AGENT_GRANTS.md.

start

supervaizer start [SCRIPT_PATH] [OPTIONS]

Loads the control script (default supervaizer_control.py, env SUPERVAIZER_SCRIPT_PATH), finds the first Server instance in it, applies the host, port, and public URL from the command line, and launches it.

Option	Env var	Default	Notes
`--public-url`	`SUPERVAIZER_PUBLIC_URL`	`scheme://host:port`	URL Studio uses to reach the controller
`--host`	`SUPERVAIZER_HOST`	`0.0.0.0`	In local mode, `0.0.0.0`, `::`, and an empty host bind `127.0.0.1`. Any other host is kept and overrides the control script
`--port`	`SUPERVAIZER_PORT`	`8000`
`--environment`	`SUPERVAIZER_ENVIRONMENT`	`dev`
`--log-level`	`SUPERVAIZER_LOG_LEVEL`	`INFO`	`SUPERVAIZER_LOG_FORMAT=json` switches to structured logs
`--persist` / `--no-persist`	`SUPERVAIZER_PERSISTENCE`	off	File persistence under `DATA_STORAGE_PATH`; see 2025_08_PERSISTENCE.md
`--local`	none	off	Local test mode, see below
`--env-file`	none	none	Loads `KEY=value` lines before the control script, for example the file that `supervaizer login` wrote. A variable that is already set keeps its value. A file that does not exist is an error

--debug and --reload are deprecated and hidden from --help; they still run and print a warning. --debug sets SUPERVAIZER_DEBUG and turns on FastAPI debug mode only in the no-script --local fallback. Set debug=True on the Server in the control script instead. Auto-reload is not supported: supervaizer start passes the app object to uvicorn, and uvicorn reloads only from an import string, so --reload only sets SUPERVAIZER_RELOAD. Restart the command after code changes.

Studio-registered controllers

When the control script sets supervisor_account and A2A endpoints are enabled (the default), launch fails unless workspace authorization is configured:

Studio-registered Supervaizer v2 A2A requires workspace authorization.
Set SUPERVAIZER_WORKSPACE_AUTH_REQUIRED=true and configure
SUPERVAIZER_WORKSPACE_AUTH_ISSUER plus either
SUPERVAIZER_WORKSPACE_AUTH_PUBLIC_KEY or SUPERVAIZER_WORKSPACE_AUTH_JWKS_URL.

supervaizer login writes these variables for you. Without it, copy the issuer and JWKS URL from Studio's Developer → Environment variables section. For production Studio, the issuer is https://studio.supervaize.com; the JWKS endpoint uses the Studio API origin and your workspace slug. The JWKS endpoint is public. This trust config is separate from the API keys used for agent-to-Studio and Studio-to-controller calls.

See 2026_05_WORKSPACE_AGENT_GRANTS.md for the model and the Supervaizer README for a complete example.

Local mode (`--local`)

supervaizer start --local

Sets SUPERVAIZER_LOCAL_MODE=true; the workspace authorization check above is skipped.
Skips Studio registration (supervisor_account is ignored).
Wildcard hosts (0.0.0.0, ::, empty) bind 127.0.0.1. An explicit host is kept and overrides the control script's Server.host. SUPERVAIZER_PUBLIC_URL is overwritten unless --public-url is passed explicitly.
Loads ./.env without overriding variables already set.
API key defaults to local-dev (override with SUPERVAIZER_API_KEY).
Adds the built-in Hello World agent next to your agents; set SUPERVAIZER_DISABLE_HELLO_WORLD=true to skip it. With no control script, only Hello World runs.
/manage (admin UI and workbench) accepts loopback connections; outside local mode it is Tailscale-only.
v2 actions and surfaces over /a2a skip workspace token checks when local mode is on, there is no supervisor_account, workspace auth is not enabled, and issuer, audience, public key, and JWKS URL are all empty. X-API-Key alone is enough, handlers get an unverified context with grant_id local-mode, and startup logs a workspace authorization is BYPASSED warning. SUPERVAIZER_WORKSPACE_AUTH_LEEWAY_SECONDS does not turn the bypass off. SUPERVAIZER_WORKSPACE_AUTH_REQUIRED=false leaves it on. With a verifier enabled, tokens are checked as in production; they also need the Studio agent id from registration, so they cannot pass in local mode. Never expose a local-mode port, and do not pass a non-loopback --host.

deploy

Requires the deploy extra and a pyproject.toml in the current directory or up to three parent directories. --name is required on every command except clean; when omitted the CLI prompts for it, even with down --yes.

Platforms: cloud-run (requires --project-id), aws-app-runner, do-app-platform. --region defaults to us-central1, us-east-1, and nyc3 respectively. --env is dev (default), staging, or prod.

# Preview (no args prints help)
supervaizer deploy plan --platform cloud-run --name my-agent --project-id my-gcp-project

# Docker smoke test on this machine (see 2025_10_LOCAL_TESTING.md)
supervaizer deploy local --name my-agent [--env dev] [--port 8000] [--generate-api-key] [--generate-rsa] [--timeout 300] [--docker-files-only] [--controller-file PATH]

# Build, push, and deploy
supervaizer deploy up --platform cloud-run --name my-agent --project-id my-gcp-project [--region us-central1] [--env dev] [--image name:tag] [--port 8000] [--generate-api-key] [--generate-rsa] [--timeout 300]

# Inspect and tear down
supervaizer deploy status --platform cloud-run --name my-agent [--env dev] [--region ...]
supervaizer deploy down   --platform cloud-run --name my-agent [--env dev] [--region ...] [--yes]   # also deletes .deployment/

# Remove local artifacts and state
supervaizer deploy clean [--force] [--docker-only] [--state-only] [--verbose]

What `deploy up` does

Builds the image --image, which defaults to {name}-{env}:{git-sha8} (:latest outside a git repo). --image takes name[:tag] only; step 2 adds the registry.
Pushes the image to the platform registry with short-lived credentials, so no docker login is needed:

Platform	Pushed reference	Credentials
`cloud-run`	`{region}-docker.pkg.dev/{project}/{repo}/{repo}:{tag}`; creates the Artifact Registry repository if missing	`gcloud auth print-access-token`
`aws-app-runner`	`{account}.dkr.ecr.{region}.amazonaws.com/{repo}:{tag}`; creates the ECR repository if missing	ECR authorization token
`do-app-platform`	`registry.digitalocean.com/{registry}/{repo}:{tag}`; uses the account registry, which must exist (`doctl registry create`)	`doctl registry docker-config`

Deploys that reference with this container environment:
- SUPERVAIZER_ENVIRONMENT, SUPERVAIZER_HOST=0.0.0.0, SUPERVAIZER_PORT (from --port, which is also the container port), and SUPERVAIZER_LOG_LEVEL (host value, else INFO).
- The host values, when set, of SUPERVAIZE_WORKSPACE_ID, SUPERVAIZE_API_URL, SUPERVAIZER_SERVER_ID, and every SUPERVAIZER_WORKSPACE_AUTH_* variable. A Studio-registered v2 controller does not start without the workspace authorization variables.
- Platform secrets: SUPERVAIZER_API_KEY (--generate-api-key), SUPERVAIZER_PRIVATE_KEY (--generate-rsa), and the host SUPERVAIZE_API_KEY, stored as {name}-{env}-api-key, {name}-{env}-rsa-key, and {name}-{env}-studio-api-key.
- SUPERVAIZER_PUBLIC_URL, set from the service URL once the first revision is ready.

The image holds no configuration or credentials, only SUPERVAIZER_PORT.

Known limits:

cloud-run: new services are private. The controller checks its own API key, so allow public invocation: gcloud run services add-iam-policy-binding {name}-{env} --region {region} --member=allUsers --role=roles/run.invoker.
cloud-run: the service identity (by default {project-number}[email protected]) needs roles/secretmanager.secretAccessor on each secret, or the revision does not start: gcloud secrets add-iam-policy-binding {name}-{env}-api-key --member=serviceAccount:{service-identity} --role=roles/secretmanager.secretAccessor.
aws-app-runner: the driver sets no ECR access role and no instance role, so App Runner cannot pull from private ECR or read Secrets Manager. Treat this platform as experimental.
Without --generate-api-key and --generate-rsa, each instance generates its own key pair at startup. When the platform runs more than one instance, pass both flags and set SUPERVAIZER_SERVER_ID.
deploy up prints failures but exits with status 0.

Design record: RFC-001.

Environment Variables

Server

Variable	Description	Default
`SUPERVAIZER_PUBLIC_URL`	URL used for inbound connections	`scheme://host:port`
`SUPERVAIZER_HOST`	Bind host	`0.0.0.0` (local mode rewrites only wildcard hosts to `127.0.0.1`)
`SUPERVAIZER_PORT`	Bind port	`8000`
`SUPERVAIZER_ENVIRONMENT`	Environment name	`dev`
`SUPERVAIZER_LOG_LEVEL`	Log level	`INFO`
`SUPERVAIZER_LOG_FORMAT`	`json` for structured logs	text
`SUPERVAIZER_API_KEY`	Controller API key (`X-API-Key`, write scope)	generated at startup, fingerprint logged; `local-dev` in local mode
`SUPERVAIZER_PRIVATE_KEY`	RSA private key (PEM)	generated per process
`SUPERVAIZER_SERVER_ID`	Stable server identity (UUID)	generated per process
`SUPERVAIZER_SCRIPT_PATH`	Control script path	`supervaizer_control.py`
`SUPERVAIZER_OUTPUT_PATH`, `SUPERVAIZER_FORCE_INSTALL`	`scaffold` output path and overwrite flag	`supervaizer_control.py`, `false`
`SUPERVAIZER_LOCAL_MODE`	Server-side local behaviour (no Studio, Hello World, `local-dev` key); the CLI flag also handles binding, `.env`, and the script fallback	`false`
`SUPERVAIZER_DISABLE_HELLO_WORLD`	Skip the built-in agent in local mode	`false`
`SUPERVAIZER_PERSISTENCE`, `DATA_STORAGE_PATH`	File persistence toggle and directory	`false`, `./data`
`TRUSTED_PROXIES`	CIDRs whose `X-Forwarded-For` is trusted for `/manage`	unset
`SUPERVAIZE_HTTP_MAX_RETRIES`	Retries for agent-to-Studio calls	`2`

Serverless (e.g. Vercel): each instance may be a new process. Set SUPERVAIZER_PRIVATE_KEY and SUPERVAIZER_SERVER_ID in the platform environment so every cold start keeps the same key and identity; Studio workspace grants are keyed on the server id.

Workspace authorization

Variable	Description	Default
`SUPERVAIZER_WORKSPACE_AUTH_REQUIRED`	Enable verification of Studio-signed workspace tokens	`false`
`SUPERVAIZER_WORKSPACE_AUTH_ISSUER`	Expected token issuer (Studio URL)	unset
`SUPERVAIZER_WORKSPACE_AUTH_PUBLIC_KEY`	Ed25519 public key (PEM)	unset
`SUPERVAIZER_WORKSPACE_AUTH_JWKS_URL`	JWKS endpoint, alternative to the PEM	unset
`SUPERVAIZER_WORKSPACE_AUTH_AUDIENCE`	Optional expected audience override	derived
`SUPERVAIZER_WORKSPACE_AUTH_LEEWAY_SECONDS`	Clock skew tolerance	`30`

Studio credentials

Read by the scaffolded control script (not by Server itself) to build the Account passed as supervisor_account:

Variable	Description
`SUPERVAIZE_API_KEY`	Agent-to-Studio API key
`SUPERVAIZE_WORKSPACE_ID`	Studio workspace identifier
`SUPERVAIZE_API_URL`	Studio base URL, e.g. `https://app.supervaize.com`

Uploaded on 2026-11-06 15:07:19

scaffold​

login​

start​

Studio-registered controllers​

Local mode (--local)​

deploy​

What deploy up does​

Environment Variables​

Server​

Workspace authorization​

Studio credentials​