CLI de Supervaizer

Créé le : 2025-08-06 Mis à jour le : 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

Crée supervaizer_control.py (la définition du contrôleur) et supervaize_instructions.html (les instructions de configuration de l'agent) dans le répertoire courant.

Le fichier de contrôle est un agent Supervaizer v2 minimal : un enregistrement, une surface job.start et une action job.start. Lancez supervaizer start --local pour l'essayer avant de connecter 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]

Cette commande vous connecte à Supervaize Studio sans clé à copier. Elle affiche une page d'approbation et un code court, et ouvre la page dans votre navigateur. Sur la page, vous vous connectez ou vous vous inscrivez (Google inclus), vérifiez que le code est identique, choisissez l'espace de travail et approuvez. La commande reçoit alors une nouvelle clé d'API développeur et écrit ces variables dans le fichier d'environnement : SUPERVAIZE_API_KEY, SUPERVAIZE_WORKSPACE_ID, SUPERVAIZE_API_URL, SUPERVAIZER_WORKSPACE_AUTH_REQUIRED, SUPERVAIZER_WORKSPACE_AUTH_ISSUER et SUPERVAIZER_WORKSPACE_AUTH_JWKS_URL.

Option	Variable d'env.	Par défaut	Notes
`--api-url`	`SUPERVAIZE_API_URL`	`https://app.supervaize.com`	Adresse de l'API de Studio
`--env-file`	aucune	`.env`	Les autres lignes du fichier restent inchangées. Un nouveau fichier n'est lisible que par son propriétaire. Un fichier nommé `.envrc` reçoit des lignes `export`
`--browser` / `--no-browser`	aucune	activé	Avec `--no-browser`, ouvrez vous-même la page affichée, sur n'importe quel appareil

La commande affiche les noms des variables, jamais une valeur. Gardez le fichier d'environnement hors de git. Le code est valable 15 minutes et pour une seule connexion. Un code refusé ou expiré n'écrit rien. Un Studio qui ne propose pas cette connexion répond par une erreur claire ; créez alors la clé depuis la page Developer de Studio.

La séquence complète, d'un projet vide à un agent dans 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

Le journal de démarrage affiche alors la page Studio de chaque agent enregistré. Ouvrez-la : un administrateur de l'espace de travail y définit la référence d'espace de travail de l'agent et accepte l'autorisation de l'espace de travail. C'est la seule étape à faire dans Studio. Consultez 2026_05_WORKSPACE_AGENT_GRANTS.md.

start

supervaizer start [SCRIPT_PATH] [OPTIONS]

Charge le script de contrôle (par défaut supervaizer_control.py, variable d'env. SUPERVAIZER_SCRIPT_PATH), trouve la première instance de Server qu'il contient, applique l'hôte, le port et l'URL publique donnés en ligne de commande, puis le lance.

Option	Variable d'env.	Par défaut	Notes
`--public-url`	`SUPERVAIZER_PUBLIC_URL`	`scheme://host:port`	URL que Studio utilise pour joindre le contrôleur
`--host`	`SUPERVAIZER_HOST`	`0.0.0.0`	En mode local, `0.0.0.0`, `::` et un hôte vide se lient à `127.0.0.1`. Tout autre hôte est conservé et remplace celui du script de contrôle
`--port`	`SUPERVAIZER_PORT`	`8000`
`--environment`	`SUPERVAIZER_ENVIRONMENT`	`dev`
`--log-level`	`SUPERVAIZER_LOG_LEVEL`	`INFO`	`SUPERVAIZER_LOG_FORMAT=json` active les journaux structurés
`--persist` / `--no-persist`	`SUPERVAIZER_PERSISTENCE`	désactivé	Persistance dans un fichier sous `DATA_STORAGE_PATH` ; voir 2025_08_PERSISTENCE.md
`--local`	aucune	désactivé	Mode de test local, voir ci-dessous
`--env-file`	aucune	aucune	Charge des lignes `KEY=value` avant le script de contrôle, par exemple le fichier écrit par `supervaizer login`. Une variable déjà définie garde sa valeur. Un fichier inexistant provoque une erreur

--debug et --reload sont obsolètes et masquées dans --help ; elles fonctionnent encore et affichent un avertissement. --debug définit SUPERVAIZER_DEBUG et active le mode debug de FastAPI uniquement dans le mode de repli --local sans script. Définissez plutôt debug=True sur le Server dans le script de contrôle. Le rechargement automatique n'est pas pris en charge : supervaizer start passe l'objet application à uvicorn, et uvicorn ne recharge qu'à partir d'une chaîne d'import ; --reload ne fait donc que définir SUPERVAIZER_RELOAD. Relancez la commande après chaque modification du code.

Contrôleurs enregistrés dans Studio

Quand le script de contrôle définit supervisor_account et que les endpoints A2A sont activés (par défaut), le lancement échoue si l'autorisation d'espace de travail n'est pas configurée :

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 écrit ces variables à votre place. Sans cette commande, copiez l'émetteur (issuer) et l'URL JWKS depuis la section Developer → Environment variables de Studio. Pour le Studio de production, l'émetteur est https://studio.supervaize.com ; le endpoint JWKS utilise l'origine de l'API de Studio et le slug de votre espace de travail. Le endpoint JWKS est public. Cette configuration de confiance est distincte des clés d'API utilisées pour les appels de l'agent vers Studio et de Studio vers le contrôleur.

Consultez 2026_05_WORKSPACE_AGENT_GRANTS.md pour le modèle et le README de Supervaizer pour un exemple complet.

Mode local (`--local`)

supervaizer start --local

Définit SUPERVAIZER_LOCAL_MODE=true ; le contrôle d'autorisation d'espace de travail ci-dessus est ignoré.
Ignore l'enregistrement dans Studio (supervisor_account est ignoré).
Les hôtes génériques (0.0.0.0, ::, vide) se lient à 127.0.0.1. Un hôte explicite est conservé et remplace le Server.host du script de contrôle. SUPERVAIZER_PUBLIC_URL est écrasée, sauf si --public-url est passée explicitement.
Charge ./.env sans remplacer les variables déjà définies.
La clé d'API vaut local-dev par défaut (remplaçable avec SUPERVAIZER_API_KEY).
Ajoute l'agent Hello World intégré à côté de vos agents ; définissez SUPERVAIZER_DISABLE_HELLO_WORLD=true pour l'omettre. Sans script de contrôle, seul Hello World s'exécute.
/manage (interface d'administration et banc d'essai) accepte les connexions de boucle locale ; hors mode local, il n'est accessible que via Tailscale.
Les actions et surfaces v2 sur /a2a ignorent les contrôles de jeton d'espace de travail quand le mode local est actif, qu'il n'y a pas de supervisor_account, que l'autorisation d'espace de travail n'est pas activée, et que l'émetteur, l'audience, la clé publique et l'URL JWKS sont tous vides. X-API-Key suffit alors, les gestionnaires reçoivent un contexte non vérifié avec le grant_id local-mode, et le démarrage journalise l'avertissement workspace authorization is BYPASSED. SUPERVAIZER_WORKSPACE_AUTH_LEEWAY_SECONDS ne désactive pas ce contournement. SUPERVAIZER_WORKSPACE_AUTH_REQUIRED=false le laisse actif. Quand un vérificateur est activé, les jetons sont contrôlés comme en production ; ils exigent aussi l'identifiant d'agent Studio obtenu à l'enregistrement, et ne peuvent donc pas passer en mode local. N'exposez jamais un port en mode local et ne passez pas d'--host hors boucle locale.

deploy

Nécessite l'extra deploy et un pyproject.toml dans le répertoire courant ou dans l'un de ses trois répertoires parents. --name est obligatoire pour toutes les commandes sauf clean ; s'il est omis, la CLI le demande, même avec down --yes.

Plateformes : cloud-run (exige --project-id), aws-app-runner, do-app-platform. --region vaut respectivement us-central1, us-east-1 et nyc3 par défaut. --env vaut dev (par défaut), staging ou 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]

Ce que fait `deploy up`

Construit l'image --image, qui vaut par défaut {name}-{env}:{git-sha8} (:latest hors d'un dépôt git). --image n'accepte que name[:tag] ; l'étape 2 ajoute le registre.
Pousse l'image vers le registre de la plateforme avec des identifiants à courte durée de vie : aucun docker login n'est nécessaire.

Plateforme	Référence poussée	Identifiants
`cloud-run`	`{region}-docker.pkg.dev/{project}/{repo}/{repo}:{tag}` ; crée le dépôt Artifact Registry s'il manque	`gcloud auth print-access-token`
`aws-app-runner`	`{account}.dkr.ecr.{region}.amazonaws.com/{repo}:{tag}` ; crée le dépôt ECR s'il manque	jeton d'autorisation ECR
`do-app-platform`	`registry.digitalocean.com/{registry}/{repo}:{tag}` ; utilise le registre du compte, qui doit exister (`doctl registry create`)	`doctl registry docker-config`

Déploie cette référence avec l'environnement de conteneur suivant :
- SUPERVAIZER_ENVIRONMENT, SUPERVAIZER_HOST=0.0.0.0, SUPERVAIZER_PORT (issu de --port, qui est aussi le port du conteneur) et SUPERVAIZER_LOG_LEVEL (valeur de l'hôte, sinon INFO).
- Les valeurs de l'hôte, quand elles sont définies, de SUPERVAIZE_WORKSPACE_ID, SUPERVAIZE_API_URL, SUPERVAIZER_SERVER_ID et de chaque variable SUPERVAIZER_WORKSPACE_AUTH_*. Un contrôleur v2 enregistré dans Studio ne démarre pas sans les variables d'autorisation d'espace de travail.
- Les secrets de la plateforme : SUPERVAIZER_API_KEY (--generate-api-key), SUPERVAIZER_PRIVATE_KEY (--generate-rsa) et le SUPERVAIZE_API_KEY de l'hôte, stockés sous les noms {name}-{env}-api-key, {name}-{env}-rsa-key et {name}-{env}-studio-api-key.
- SUPERVAIZER_PUBLIC_URL, définie à partir de l'URL du service dès que la première révision est prête.

L'image ne contient ni configuration ni identifiants, seulement SUPERVAIZER_PORT.

Limites connues :

cloud-run : les nouveaux services sont privés. Le contrôleur vérifie lui-même sa clé d'API ; autorisez donc l'invocation publique : gcloud run services add-iam-policy-binding {name}-{env} --region {region} --member=allUsers --role=roles/run.invoker.
cloud-run : l'identité du service (par défaut {project-number}[email protected]) a besoin de roles/secretmanager.secretAccessor sur chaque secret, sinon la révision ne démarre pas : gcloud secrets add-iam-policy-binding {name}-{env}-api-key --member=serviceAccount:{service-identity} --role=roles/secretmanager.secretAccessor.
aws-app-runner : le pilote ne définit ni rôle d'accès ECR ni rôle d'instance ; App Runner ne peut donc ni tirer depuis un ECR privé ni lire Secrets Manager. Considérez cette plateforme comme expérimentale.
Sans --generate-api-key ni --generate-rsa, chaque instance génère sa propre paire de clés au démarrage. Quand la plateforme exécute plusieurs instances, passez les deux options et définissez SUPERVAIZER_SERVER_ID.
deploy up affiche les échecs mais se termine avec le code de sortie 0.

Document de conception : RFC-001.

Variables d'environnement

Serveur

Variable	Description	Par défaut
`SUPERVAIZER_PUBLIC_URL`	URL utilisée pour les connexions entrantes	`scheme://host:port`
`SUPERVAIZER_HOST`	Hôte de liaison	`0.0.0.0` (le mode local ne réécrit que les hôtes génériques en `127.0.0.1`)
`SUPERVAIZER_PORT`	Port de liaison	`8000`
`SUPERVAIZER_ENVIRONMENT`	Nom de l'environnement	`dev`
`SUPERVAIZER_LOG_LEVEL`	Niveau de journalisation	`INFO`
`SUPERVAIZER_LOG_FORMAT`	`json` pour des journaux structurés	texte
`SUPERVAIZER_API_KEY`	Clé d'API du contrôleur (`X-API-Key`, droit d'écriture)	générée au démarrage, empreinte journalisée ; `local-dev` en mode local
`SUPERVAIZER_PRIVATE_KEY`	Clé privée RSA (PEM)	générée par processus
`SUPERVAIZER_SERVER_ID`	Identité stable du serveur (UUID)	générée par processus
`SUPERVAIZER_SCRIPT_PATH`	Chemin du script de contrôle	`supervaizer_control.py`
`SUPERVAIZER_OUTPUT_PATH`, `SUPERVAIZER_FORCE_INSTALL`	Chemin de sortie de `scaffold` et indicateur d'écrasement	`supervaizer_control.py`, `false`
`SUPERVAIZER_LOCAL_MODE`	Comportement local côté serveur (pas de Studio, Hello World, clé `local-dev`) ; l'option de la CLI gère aussi la liaison, `.env` et le repli sans script	`false`
`SUPERVAIZER_DISABLE_HELLO_WORLD`	Omet l'agent intégré en mode local	`false`
`SUPERVAIZER_PERSISTENCE`, `DATA_STORAGE_PATH`	Activation de la persistance dans un fichier et répertoire	`false`, `./data`
`TRUSTED_PROXIES`	CIDR dont le `X-Forwarded-For` est approuvé pour `/manage`	non défini
`SUPERVAIZE_HTTP_MAX_RETRIES`	Nombre de nouvelles tentatives pour les appels de l'agent vers Studio	`2`

Serverless (par ex. Vercel) : chaque instance peut être un nouveau processus. Définissez SUPERVAIZER_PRIVATE_KEY et SUPERVAIZER_SERVER_ID dans l'environnement de la plateforme pour que chaque démarrage à froid conserve la même clé et la même identité ; les autorisations d'espace de travail de Studio sont indexées sur l'identifiant du serveur.

Autorisation d'espace de travail

Variable	Description	Par défaut
`SUPERVAIZER_WORKSPACE_AUTH_REQUIRED`	Active la vérification des jetons d'espace de travail signés par Studio	`false`
`SUPERVAIZER_WORKSPACE_AUTH_ISSUER`	Émetteur de jeton attendu (URL de Studio)	non défini
`SUPERVAIZER_WORKSPACE_AUTH_PUBLIC_KEY`	Clé publique Ed25519 (PEM)	non défini
`SUPERVAIZER_WORKSPACE_AUTH_JWKS_URL`	Endpoint JWKS, alternative au PEM	non défini
`SUPERVAIZER_WORKSPACE_AUTH_AUDIENCE`	Remplacement facultatif de l'audience attendue	dérivée
`SUPERVAIZER_WORKSPACE_AUTH_LEEWAY_SECONDS`	Tolérance de décalage d'horloge	`30`

Identifiants Studio

Lus par le script de contrôle généré (pas par Server lui-même) pour construire l'Account passé en supervisor_account :

Variable	Description
`SUPERVAIZE_API_KEY`	Clé d'API de l'agent vers Studio
`SUPERVAIZE_WORKSPACE_ID`	Identifiant de l'espace de travail Studio
`SUPERVAIZE_API_URL`	URL de base de Studio, par ex. `https://app.supervaize.com`

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

scaffold​

login​

start​

Contrôleurs enregistrés dans Studio​

Mode local (--local)​

deploy​

Ce que fait deploy up​

Variables d'environnement​

Serveur​

Autorisation d'espace de travail​

Identifiants Studio​