Referencia de la CLI¶
El comando provisa es el único punto de entrada para el nivel embebido instalado con pip (REQ-1128).
Inicia el runtime, gestiona licencias, dispara la publicación de metadatos, despliega modelos, y
controla el banner de mantenimiento — sin Docker, Node, ni ningún servicio externo.
Instálelo con el extra embedded, que también trae las extensiones DuckDB sin conexión
y el plano de control PostgreSQL embebido:
Requisitos de plataforma. provisa run requiere Python 3.12 y una plataforma con un wheel de
pgserver: linux x86_64, macOS, o Windows x86_64. Linux aarch64 no tiene wheel de pgserver ni
distribución de fuentes, así que el nivel embebido no se ejecuta ahí. Use el nivel de contenedor en
aarch64.
[tool-verified: _require_supported_interpreter() at cli.py:513-546]
Opciones compartidas¶
Varios subcomandos llaman a la API HTTP de Provisa. Comparten tres flags y dos variables de
entorno. [tool-verified: _api_call() at cli.py:345-376; each subcommand's argparse block
at cli.py:653-773]
| Flag | Predeterminado | Fallback a variable de entorno |
|---|---|---|
--api <url> |
http://127.0.0.1:8000 |
PROVISA_API_URL |
--token <token> |
(ninguno) | PROVISA_API_TOKEN |
--timeout <seconds> |
300 (30 para maintenance) |
(ninguno) |
--api es la URL base de una instancia de Provisa en ejecución. Bajo multiinquilinato el host
nombra la organización — https://acme.provisa.org enruta al tenant de acme. --token es un
token Bearer; cuando está vacío no se envía ningún encabezado Authorization, lo cual es correcto
para despliegues sin autenticación. [tool-verified: cli.py:314-316, 357-365]
Establezca ambas variables en su entorno de CI para evitar repetirlas en cada llamada:
Subcomandos que aceptan estos flags: metadata export, cada subcomando env (list, show,
create, delete, diff, merge, deploy, revert, redo, fetch, push, pull),
maintenance on, maintenance off, maintenance status.
provisa run¶
Inicia el sistema Provisa embebido — servidor de API y servidor estático/proxy de la UI — en un
solo proceso. Sin Docker, sin Node, sin servicios externos. [tool-verified: cli.py module docstring lines 11-23;
_cmd_run() at cli.py:549-602]
provisa run [--demo] [--host HOST] [--api-port PORT] [--ui-port PORT]
[--no-browser] [--reset] [--data-dir DIR]
Flags¶
| Flag | Predeterminado | Notas |
|---|---|---|
--demo |
desactivado | Carga la demo incluida — dominios de ejemplo pet-store y shelter sobre SQLite embebido (REQ-414) |
--host |
127.0.0.1 |
Dirección de enlace para ambos servidores |
--api-port |
8000 |
Puerto del servidor de API |
--ui-port |
3000 |
Puerto del servidor estático/proxy de la UI |
--no-browser |
desactivado | Omite abrir un navegador cuando la UI está lista; igual imprime la URL |
--reset |
desactivado | Descarta y reconstruye el almacén del plano de control embebido antes de iniciar; úselo después de una actualización de Provisa si el arranque reporta un desajuste de esquema |
--data-dir |
~/.provisa/native |
Directorio que contiene el clúster PostgreSQL embebido y la caché de extensiones DuckDB |
[tool-verified: run subparser at cli.py:609-634]
Variables de entorno¶
provisa run lee varias variables adicionales antes de que arranquen los servidores HTTP.
Establézcalas para anular los valores predeterminados que aplicaría load_profile("native", ...).
[tool-verified: _apply_embedded_env() at cli.py:83-116]
| Variable | Efecto |
|---|---|
TRINO_HOST / TRINO_PORT |
Reemplaza el motor DuckDB embebido por un coordinador Trino suministrado por el cliente (REQ-1129) |
PROVISA_ENGINE_URL |
Forma alternativa de apuntar a un motor de federación externo |
PROVISA_CONFIG |
Archivo de configuración a cargar; --demo lo establece en la configuración de demo incluida (REQ-1127) |
PROVISA_DEMO |
Establecida en 1 por --demo; marca la sesión como una ejecución de demo |
PROVISA_DEMO_DIR |
Ruta al directorio de datos de muestra de la demo; establecida por --demo |
PROVISA_DUCKDB_EXT_DIR |
Directorio de extensiones DuckDB preparado de antemano; se establece automáticamente desde el paquete provisa-duckdb-ext si está presente; su ausencia significa que DuckDB descarga desde la red en el primer uso |
[tool-verified: _apply_demo_config() at cli.py:67-80; _apply_embedded_env() at cli.py:83-116]
Secuencia de arranque¶
- Verificación de plataforma — aborta con un mensaje claro ante un Python no compatible o un pgserver faltante.
--reset(si se solicita) — descarta el clúster PostgreSQL embebido; se reconstruye en el siguiente paso.- Configuración de demo (si
--demo) — establecePROVISA_CONFIGyPROVISA_DEMO_DIR. - Entorno embebido — inicia el plano de control PostgreSQL, resuelve su URL de socket, y
prepara las extensiones DuckDB sin conexión si
provisa-duckdb-extestá instalado. - Verificación de desviación de esquema — escanea el plano de control en vivo en busca de columnas
faltantes. Si encuentra alguna, imprime una sugerencia de
--resety sale con código 1. V1 no tiene migraciones; una columna agregada en una versión más nueva requiere un reset. [tool-verified:_control_plane_drift()at cli.py:119-162] - Ambos servidores arrancan de forma concurrente. El anunciador de disponibilidad sondea
GET /ready(no/health— el endpoint/readyconfirma que el almacén está conectado y el motor está caliente) y abre el navegador cuando devuelve 200. [tool-verified:_announce_ready()at cli.py:182-224]
Códigos de salida¶
| Código | Significado |
|---|---|
| 0 | Apagado limpio (Ctrl-C) |
| 1 | Error de arranque (falló la verificación de plataforma, falta la configuración de demo, se detectó desviación de esquema) |
Ejemplo¶
# Start with the demo data
provisa run --demo
# Start on non-default ports, no browser
provisa run --api-port 8080 --ui-port 4000 --no-browser
# Upgrade: reset the control plane first, then start
provisa run --reset
# Point at an external Trino cluster instead of the embedded DuckDB engine
TRINO_HOST=trino.internal TRINO_PORT=8080 provisa run
provisa license apply¶
Verifica e instala un archivo de licencia sin conexión (REQ-1139). El archivo es el license.json
emitido por provisa.dev. [tool-verified: _cmd_license_apply() at cli.py:271-280]
| Argumento | Notas |
|---|---|
file |
Ruta al archivo de licencia; se aplica expansión de ~ |
Código de salida 0 significa que la licencia es válida y está instalada. Código de salida 1 significa que fue rechazada; la razón se imprime a stderr. [tool-verified: cli.py:276-280]
provisa license status¶
Muestra el ID de máquina, el estado de prueba, los días transcurridos, y la validez de la licencia (REQ-1139).
[tool-verified: _cmd_license_status() at cli.py:283-299]
Sin flags. Imprime cuatro líneas — ID de máquina, fecha de primera vista, días transcurridos, estado de prueba, y estado de licencia — y sale con 0. [tool-verified: cli.py:293-299]
Machine ID: a1b2c3d4e5f6...
First seen: 2026-07-01
Elapsed: 83.0 days
Trial: active
Licensed: no (no license installed)
provisa metadata export¶
Dispara la publicación de metadatos a demanda del servidor en ejecución (REQ-1072/REQ-1074).
Hace POST a POST /admin/metadata-export/publish — el mismo endpoint que llama el botón
Publish now de la pestaña Admin, así que ambas rutas envían la misma instantánea completa. [tool-verified: _cmd_metadata_export()
at cli.py:302-342]
| Flag | Predeterminado | Notas |
|---|---|---|
--api |
$PROVISA_API_URL, luego http://127.0.0.1:8000 |
Bajo multiinquilinato el host nombra la organización |
--token |
$PROVISA_API_TOKEN |
Token Bearer para una identidad que posea org_settings; omítalo en despliegues sin autenticación |
--timeout |
300 |
Segundos antes de que se abandone la llamada HTTP |
[tool-verified: cli.py:654-669]
| Código de salida | Significado |
|---|---|
| 0 | Todo activo publicado |
| 1 | Publicación parcial o fallo de conexión; los errores por activo se imprimen a stderr |
[tool-verified: cli.py:335-342]
provisa metadata export \
--api https://acme.provisa.org \
--token "$PROVISA_API_TOKEN"
# Cron example — daily at 06:00
# 0 6 * * * provisa metadata export --api https://acme.provisa.org >> /var/log/provisa-export.log 2>&1
La referencia de configuración completa — proveedores, credenciales, reconcile_cron, y qué
contiene la instantánea — está en
Metadata Export.
provisa env¶
Ejecuta el ciclo de vida de los entornos contra un Provisa en marcha (REQ-1498). Cada subcomando es una llamada a la API de administración que llama la interfaz; la CLI no decide nada. La lista de lo que lleva una copia, las reglas de fusión y eliminación, la vinculación, la protección y los derechos de quien llama son del servidor, así que se cumplen se invoque como se invoque la operación. [tool-verified: cli_envs.py:11-28]
Flags que acepta cada subcomando¶
| Flag | Obligatorio | Notas |
|---|---|---|
--org |
sí | Organización que tiene el entorno |
--json |
no | Imprime la respuesta de la API como JSON, para un script |
--api |
no | Consulte Opciones compartidas |
--token |
no | Token bearer de una identidad que puede realizar la operación |
--timeout |
no | Segundos; por defecto 300 |
Los subcomandos que actúan sobre un entorno también aceptan --env ENV (obligatorio). list, diff,
merge y fetch no; diff y merge nombran sus entornos con --from y --into.
[tool-verified: cli_envs.py:349-374, _command()]
Códigos de salida¶
| Código | Significado |
|---|---|
| 0 | Hecho, o un ensayo que no aplicó nada |
| 1 | Rechazado. El código de la regla que rechaza se imprime en stderr como refused (<code>): <detail>; con --json es {"refused": {...}} en stdout |
| 2 | Propuesto, no aplicado: el entorno de destino está protegido y el cambio espera una aprobación |
El código de salida 2 es intencionado. Un pipeline que tratara una aprobación pendiente como un despliegue publicado se equivocaría. [tool-verified: cli_envs.py:21-28, 40-41, 64-78, 120-135]
provisa env list¶
Lista los entornos de la organización y la build en la que está cada uno. Sin flags aparte de los compartidos. [tool-verified: cli_envs.py:141-149]
provisa env show¶
Muestra un entorno y su build actual. Sale con 1 y environments.unknown cuando el
entorno no existe. [tool-verified: cli_envs.py:163-183]
provisa env create¶
Crea un entorno que contiene el modelo de otro, con sus datos elegidos al crearlo (REQ-1942). La API decide qué opciones puede tomar quien llama. [tool-verified: cli_envs.py:197-216]
provisa env create --org ORG --env NAME --data-mode MODE
[--from SOURCE] [--mutation-handling HANDLING] [--expires-at ISO8601]
--env | sí | Nombre del nuevo entorno |
| --from | no | Entorno del que partir; por defecto prod |
| --data-mode | sí | inherit, unbound, test_fake o test_synthetic: las conexiones del origen por referencia, ninguna hasta que vincule las suyas, o datos de prueba |
| --mutation-handling | no | refused, reversible o direct; por defecto refused |
| --expires-at | no | Instante ISO-8601 tras el cual se elimina el entorno |
[tool-verified: cli_envs.py:391-416]
provisa env delete¶
Retira un entorno. Sus ramas solo se van cuando se nombran. [tool-verified: cli_envs.py:219-232]
| Flag | Notas | | --- | --- | |--delete-branch | Elimina también su rama |
| --delete-remote-branch | Elimina también su rama en el remoto |
[tool-verified: cli_envs.py:418-424]
provisa env diff¶
Informa de lo que haría fusionar un entorno en otro. Es un GET de merge-preview, así que
no puede escribir; déselo a un runner que no deba cambiar nada. [tool-verified:
cli_envs.py:186-191]
--from | sí | Entorno desde el que se fusiona |
| --into | sí | Entorno en el que se fusiona |
| --removals | no | Quita también del destino lo que el origen ya no tiene |
| --select PATH | no | Limita la fusión a este objeto, por su ruta en el modelo (metrics/revenue.yaml); repítalo para más. Lo que requiere y le falta al destino se lleva con él y se lista (REQ-1506) |
[tool-verified: cli_envs.py:426-439]
provisa env merge¶
Fusiona un entorno en otro, por identidad (REQ-1490). [tool-verified: cli_envs.py:235-250]
provisa env merge --org ORG --from SOURCE --into TARGET
[--removals] [--select PATH ...] [--dry-run] [--message MSG]
[--retire-source] [--retire-remote]
--from | sí | Entorno desde el que se fusiona |
| --into | sí | Entorno en el que se fusiona |
| --removals | no | Quita también del destino lo que el origen ya no tiene |
| --select PATH | no | Limita la fusión a este objeto, por su ruta en el modelo (metrics/revenue.yaml); repítalo para más. Lo que requiere y le falta al destino se lleva con él y se lista (REQ-1506) |
| --dry-run | no | Imprime el informe de fusión y no aplica nada |
| --message | no | Qué hace la fusión; obligatorio para aplicar |
| --retire-source | no | Elimina el origen cuando su trabajo ha llegado |
| --retire-remote | no | Con --retire-source, elimina también la rama del origen en el remoto |
[tool-verified: cli_envs.py:429-451]
provisa env deploy¶
Despliega el modelo de una ref de git en un entorno, haciendo de ese árbol el modelo actual del entorno (REQ-1496). Es el comando que ejecuta un pipeline de despliegue; un despliegue es siempre una invocación con una identidad contra un plano de control nombrado. [tool-verified: cli_envs.py:253-267]
| Flag | Obligatorio | Notas | | --- | --- | --- | |--env | sí | Entorno que tendrá el modelo desplegado |
| --ref | sí | Rama o commit del repositorio de la organización |
| --dry-run | no | Informa de lo que haría el despliegue; no aplica nada |
| --message | no | Nota que se lleva a una solicitud de aprobación cuando el destino está protegido |
[tool-verified: cli_envs.py:453-468]
Una carga en un entorno existente nunca aplica roles. --seed ya no existe: la API rechaza una siembra
con environments.seed_only_at_creation.
# Fetch remote branches, then deploy
provisa env fetch --org acme --api "$PROVISA_API_URL" --token "$PROVISA_API_TOKEN"
provisa env deploy \
--org acme --env prod --ref "origin/main" \
--message "release: $GIT_COMMIT_MSG" \
--api "$PROVISA_API_URL" --token "$PROVISA_API_TOKEN"
provisa env revert¶
Devuelve un entorno a una build anterior (REQ-1543). Sin --to retrocede un commit
en la historia propia del entorno. Con --to es el despliegue ordinario de esa build.
[tool-verified: cli_envs.py:270-284]
--env | sí | Entorno que se revierte |
| --to | no | Build que se despliega; por defecto la anterior a la build actual |
| --message | no | Nota que se lleva a una solicitud de aprobación |
[tool-verified: cli_envs.py:470-480]
provisa env redo¶
Avanza de nuevo hacia la build de la que partió una reversión. [tool-verified: cli_envs.py:287-301]
provisa env fetch¶
Trae las ramas remotas de la organización a su repositorio de Provisa (REQ-1541). Ejecútelo antes de un despliegue
cuando quiera nombrar origin/<branch>. Provisa nunca lo ejecuta con un temporizador. [tool-verified:
cli_envs.py:307-320]
origin/<name> <sha12>.
provisa env fetch --org acme --api "$PROVISA_API_URL" --token "$PROVISA_API_TOKEN"
# origin/main a1b2c3d4e5f6
# origin/dev 9f8e7d6c5b4a
provisa env push¶
Envía la rama de un entorno al remoto de la organización (REQ-1546). Imprime nothing to send cuando
no hay nada que enviar. [tool-verified: cli_envs.py:323-331]
provisa env pull¶
Aplica lo que el remoto tiene para un entorno (REQ-1547). Imprime
<env> already holds what the remote does cuando no hay nada que aplicar. El código de salida 2 se aplica igual
que en deploy. [tool-verified: cli_envs.py:334-343]
provisa maintenance on¶
Activa el banner de mantenimiento programado en el despliegue (REQ-1466). Ejecute esto antes de un
trabajo planificado que desconecte el plano de datos — por ejemplo, antes de cambiar
var.engine_cluster_mode, lo cual reemplaza el clúster del motor y cada shard en él (REQ-1465).
[tool-verified: _cmd_maintenance_on() at cli.py:483-495]
provisa maintenance on [--message MSG] [--ends-at ISO8601]
[--api URL] [--token TOKEN] [--timeout SECONDS]
| Flag | Notas |
|---|---|
--message |
Anula el texto estándar del despliegue; el predeterminado es el mensaje estándar del servidor |
--ends-at |
Instante ISO-8601 en que se espera que termine el trabajo, p. ej. 2026-08-14T22:30:00Z; el predeterminado es sin estimación |
--api |
Véase Opciones compartidas |
--token |
Token Bearer para una identidad que posea platform_settings |
--timeout |
Predeterminado 30 s |
[tool-verified: cli.py:743-773]
Imprime el estado resultante del banner y sale con 0. Lanza SystemExit ante un fallo HTTP o de conexión.
provisa maintenance on \
--message "Engine cluster rolling upgrade" \
--ends-at "2026-09-22T03:00:00Z" \
--api "$PROVISA_API_URL" --token "$PROVISA_API_TOKEN"
provisa maintenance off¶
Desactiva el banner de mantenimiento una vez terminado el trabajo (REQ-1466).
[tool-verified: _cmd_maintenance_off() at cli.py:498-501]
Imprime el estado resultante del banner (active: false) y sale con 0.
provisa maintenance off --api "$PROVISA_API_URL" --token "$PROVISA_API_TOKEN"
# Maintenance notice: OFF
provisa maintenance status¶
Muestra el estado actual del banner de mantenimiento sin cambiarlo (REQ-1466).
[tool-verified: _cmd_maintenance_status() at cli.py:504-507]
Imprime el estado del banner y sale con 0.
Maintenance notice: ON
Message: Engine cluster rolling upgrade
Since: 2026-09-22T01:15:00Z
Ends at: 2026-09-22T03:00:00Z
Referencia rápida¶
| Comando | REQ | Qué hace |
|---|---|---|
provisa run |
REQ-1128 | Inicia la API + UI embebidas |
provisa run --demo |
REQ-414 | Inicia con datos de muestra pet-store / shelter |
provisa run --reset |
REQ-1535 | Reconstruye el plano de control antes de iniciar |
provisa license apply <file> |
REQ-1139 | Instala un archivo de licencia sin conexión |
provisa license status |
REQ-1139 | Muestra el ID de máquina y el estado de prueba/licencia |
provisa metadata export |
REQ-1072 | Publica la instantánea de metadatos a demanda |
provisa env list --org ORG |
REQ-1498 | Lista los entornos de la organización y sus builds |
provisa env show --org ORG --env ENV |
REQ-1498 | Muestra un entorno |
provisa env create --org ORG --env ENV --data-mode MODE |
REQ-1942 | Crea un entorno a partir de otro |
provisa env delete --org ORG --env ENV |
REQ-1498 | Retira un entorno |
provisa env diff --org ORG --from A --into B |
REQ-1490 | Vista previa de una fusión (solo lectura) |
provisa env merge --org ORG --from A --into B |
REQ-1490 | Fusiona un entorno en otro |
provisa env deploy --org ORG --env ENV --ref REF |
REQ-1496 | Despliega una ref en un entorno |
provisa env revert --org ORG --env ENV [--to BUILD] |
REQ-1543 | Retrocede un commit, o despliega una build |
provisa env redo --org ORG --env ENV |
REQ-1543 | Vuelve a avanzar |
provisa env fetch --org ORG |
REQ-1541 | Trae las ramas remotas al repositorio de Provisa |
provisa env push --org ORG --env ENV |
REQ-1546 | Envía la rama de un entorno al remoto |
provisa env pull --org ORG --env ENV |
REQ-1547 | Aplica lo que tiene el remoto |
provisa maintenance on |
REQ-1466 | Activa el banner de mantenimiento |
provisa maintenance off |
REQ-1466 | Desactiva el banner de mantenimiento |
provisa maintenance status |
REQ-1466 | Muestra el estado actual del banner |
Véase también¶
- Entornos — modelo de entornos, entornos protegidos, ciclo de vida de aprobación de deploy
- Metadata Export — proveedores de catálogo, configuración, y qué contiene la instantánea
- Deployment — nivel de contenedor y despliegue en la nube