Справочник CLI¶
Команда provisa — единая точка входа для встраиваемого уровня, устанавливаемого через pip (REQ-1128).
Она запускает среду выполнения, управляет лицензиями, инициирует публикацию метаданных, разворачивает модели и
управляет баннером обслуживания — без Docker, Node или каких-либо внешних сервисов.
Установите её с дополнительным пакетом embedded, который также подтягивает офлайн-расширения
DuckDB и встроенную плоскость управления PostgreSQL:
Требования к платформе. provisa run требует Python 3.12 и платформу с колесом (wheel) pgserver:
linux x86_64, macOS или Windows x86_64. У Linux aarch64 нет ни колеса pgserver, ни исходного
дистрибутива, поэтому встраиваемый уровень там не работает. Используйте контейнерный уровень на aarch64.
[tool-verified: _require_supported_interpreter() at cli.py:513-546]
Общие параметры¶
Несколько подкоманд вызывают HTTP API Provisa. Они разделяют три флага и две переменные
окружения. [tool-verified: _api_call() at cli.py:345-376; each subcommand's argparse block
at cli.py:653-773]
| Флаг | По умолчанию | Резервная переменная окружения |
|---|---|---|
--api <url> |
http://127.0.0.1:8000 |
PROVISA_API_URL |
--token <token> |
(отсутствует) | PROVISA_API_TOKEN |
--timeout <seconds> |
300 (30 для maintenance) |
(отсутствует) |
--api — это базовый URL работающего экземпляра Provisa. В условиях многоарендности имя хоста
называет организацию — https://acme.provisa.org направляет к тенанту acme. --token — это
Bearer-токен; когда он пуст, заголовок Authorization не отправляется, что верно для
неавторизованных развёртываний. [tool-verified: cli.py:314-316, 357-365]
Задайте обе переменные в вашем окружении CI, чтобы не повторять их при каждом вызове:
Подкоманды, принимающие эти флаги: metadata export, каждая подкоманда env (list, show,
create, delete, diff, merge, deploy, revert, redo, fetch, push, pull),
maintenance on, maintenance off, maintenance status.
provisa run¶
Запустить встраиваемую систему Provisa — API-сервер и статический/прокси-сервер интерфейса — в одном
процессе. Без Docker, без Node, без внешних сервисов. [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]
Флаги¶
| Флаг | По умолчанию | Примечания |
|---|---|---|
--demo |
выкл | Загрузить встроенную демонстрацию — примеры доменов pet-store и shelter поверх встроенного SQLite (REQ-414) |
--host |
127.0.0.1 |
Адрес привязки для обоих серверов |
--api-port |
8000 |
Порт API-сервера |
--ui-port |
3000 |
Порт статического/прокси-сервера интерфейса |
--no-browser |
выкл | Пропустить открытие браузера при готовности интерфейса; URL всё равно выводится |
--reset |
выкл | Удалить и пересоздать хранилище встроенной плоскости управления перед запуском; используйте после обновления Provisa, если запуск сообщает о несоответствии схемы |
--data-dir |
~/.provisa/native |
Каталог, содержащий встроенный кластер PostgreSQL и кеш расширений DuckDB |
[tool-verified: run subparser at cli.py:609-634]
Переменные окружения¶
provisa run читает несколько дополнительных переменных перед запуском HTTP-серверов.
Задайте их, чтобы переопределить значения по умолчанию, которые иначе применил бы load_profile("native", ...).
[tool-verified: _apply_embedded_env() at cli.py:83-116]
| Переменная | Эффект |
|---|---|
TRINO_HOST / TRINO_PORT |
Заменяет встроенный движок DuckDB на предоставленный клиентом координатор Trino (REQ-1129) |
PROVISA_ENGINE_URL |
Альтернативный способ указать на внешний федеративный движок |
PROVISA_CONFIG |
Файл конфигурации для загрузки; --demo устанавливает его во встроенную демонстрационную конфигурацию (REQ-1127) |
PROVISA_DEMO |
Устанавливается в 1 флагом --demo; помечает сессию как демонстрационный запуск |
PROVISA_DEMO_DIR |
Путь к каталогу примеров данных для демонстрации; устанавливается флагом --demo |
PROVISA_DUCKDB_EXT_DIR |
Заранее подготовленный каталог расширений DuckDB; устанавливается автоматически из пакета provisa-duckdb-ext, если он присутствует; отсутствие означает, что DuckDB загрузится из сети при первом использовании |
[tool-verified: _apply_demo_config() at cli.py:67-80; _apply_embedded_env() at cli.py:83-116]
Последовательность запуска¶
- Проверка платформы — прерывает работу с понятным сообщением при неподдерживаемом Python или отсутствующем pgserver.
--reset(если запрошен) — удаляет встроенный кластер PostgreSQL; он пересоздаётся на следующем шаге.- Демонстрационная конфигурация (если
--demo) — устанавливаетPROVISA_CONFIGиPROVISA_DEMO_DIR. - Встроенное окружение — запускает плоскость управления PostgreSQL, разрешает её URL сокета и
подготавливает офлайн-расширения DuckDB, если установлен
provisa-duckdb-ext. - Проверка расхождения схемы — сканирует действующую плоскость управления на предмет отсутствующих столбцов. Если такие найдены,
выводится подсказка о
--reset, и работа завершается с кодом 1. В V1 нет миграций; столбец, добавленный в более новом релизе, требует сброса. [tool-verified:_control_plane_drift()at cli.py:119-162] - Оба сервера запускаются одновременно. Индикатор готовности опрашивает
GET /ready(не/health— конечная точка/readyподтверждает, что хранилище подключено и движок прогрет) и открывает браузер, когда получает 200. [tool-verified:_announce_ready()at cli.py:182-224]
Коды завершения¶
| Код | Значение |
|---|---|
| 0 | Чистое завершение (Ctrl-C) |
| 1 | Ошибка запуска (не пройдена проверка платформы, отсутствует демонстрационная конфигурация, обнаружено расхождение схемы) |
Пример¶
# 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¶
Проверить и установить файл лицензии офлайн (REQ-1139). Файл — это license.json, выданный
provisa.dev. [tool-verified: _cmd_license_apply() at cli.py:271-280]
| Аргумент | Примечания |
|---|---|
file |
Путь к файлу лицензии; применяется раскрытие ~ |
Код завершения 0 означает, что лицензия действительна и установлена. Код завершения 1 означает, что она была отклонена; причина выводится в stderr. [tool-verified: cli.py:276-280]
provisa license status¶
Показать идентификатор машины, состояние пробного периода, прошедшие дни и действительность лицензии (REQ-1139).
[tool-verified: _cmd_license_status() at cli.py:283-299]
Без флагов. Выводит четыре строки — идентификатор машины, дату первого обнаружения, прошедшие дни, состояние пробного периода и состояние лицензии — и завершается с кодом 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¶
Инициировать публикацию метаданных по требованию на работающем сервере (REQ-1072/REQ-1074). Отправляет POST на
POST /admin/metadata-export/publish — ту же конечную точку, которую вызывает кнопка Publish now
на вкладке Admin, поэтому оба пути отправляют один и тот же полный снимок. [tool-verified: _cmd_metadata_export()
at cli.py:302-342]
| Флаг | По умолчанию | Примечания |
|---|---|---|
--api |
$PROVISA_API_URL, затем http://127.0.0.1:8000 |
В условиях многоарендности имя хоста называет организацию |
--token |
$PROVISA_API_TOKEN |
Bearer-токен для идентификации, обладающей org_settings; опустите на неавторизованных развёртываниях |
--timeout |
300 |
Секунды до отмены HTTP-вызова |
[tool-verified: cli.py:654-669]
| Код завершения | Значение |
|---|---|
| 0 | Все активы опубликованы |
| 1 | Частичная публикация или сбой подключения; ошибки по каждому активу выводятся в 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
Полный справочник конфигурации — провайдеры, учётные данные, reconcile_cron и содержимое
снимка — в разделе Экспорт метаданных.
provisa env¶
Выполняет жизненный цикл окружений против работающего Provisa (REQ-1498). Каждая подкоманда — это вызов API администратора, который вызывает интерфейс; CLI ничего не решает. Список того, что переносит копия, правила слияния и удаления, привязка, защита и права вызывающего принадлежат серверу, поэтому действуют независимо от того, как вызвана операция. [tool-verified: cli_envs.py:11-28]
Флаги, которые принимает каждая подкоманда¶
| Флаг | Обязательный | Примечания |
|---|---|---|
--org |
да | Организация, которой принадлежит окружение |
--json |
нет | Печатает ответ API как JSON, для скрипта |
--api |
нет | См. Общие параметры |
--token |
нет | Bearer-токен идентичности, которой разрешена операция |
--timeout |
нет | Секунды; по умолчанию 300 |
Подкоманды, действующие на одно окружение, также принимают --env ENV (обязательно). list, diff,
merge и fetch — нет; diff и merge называют свои окружения через --from и --into.
[tool-verified: cli_envs.py:349-374, _command()]
Коды выхода¶
| Код | Значение |
|---|---|
| 0 | Готово, или пробный запуск, который ничего не применил |
| 1 | Отклонено. Код отклонившего правила печатается в stderr как refused (<code>): <detail>; с --json это {"refused": {...}} в stdout |
| 2 | Предложено, не применено: целевое окружение защищено, и изменение ждёт одобрения |
Код выхода 2 намеренный. Конвейер, который считал бы ожидающее одобрение выпущенным развёртыванием, ошибался бы. [tool-verified: cli_envs.py:21-28, 40-41, 64-78, 120-135]
provisa env list¶
Перечисляет окружения организации и сборку, на которой находится каждое. Никаких флагов, кроме общих. [tool-verified: cli_envs.py:141-149]
provisa env show¶
Показывает одно окружение и его текущую сборку. Завершается с 1 и environments.unknown, если
окружение не существует. [tool-verified: cli_envs.py:163-183]
provisa env create¶
Создаёт окружение, содержащее модель другого, с данными, выбранными при создании (REQ-1942). API решает, какой выбор может сделать вызывающий. [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 | да | Имя нового окружения |
| --from | нет | Окружение, от которого начинать; по умолчанию prod |
| --data-mode | да | inherit, unbound, test_fake или test_synthetic: подключения источника по ссылке, никаких, пока оно не привяжет свои, или тестовые данные |
| --mutation-handling | нет | refused, reversible или direct; по умолчанию refused |
| --expires-at | нет | Момент ISO-8601, после которого окружение удаляется |
[tool-verified: cli_envs.py:391-416]
provisa env delete¶
Выводит окружение из эксплуатации. Его ветки удаляются, только если названы. [tool-verified: cli_envs.py:219-232]
| Флаг | Примечания | | --- | --- | |--delete-branch | Удаляет также его ветку |
| --delete-remote-branch | Удаляет также его ветку на удалённом репозитории |
[tool-verified: cli_envs.py:418-424]
provisa env diff¶
Сообщает, что сделало бы слияние одного окружения в другое. Это GET merge-preview, поэтому
он не может писать; отдайте его раннеру, который не должен ничего менять. [tool-verified:
cli_envs.py:186-191]
--from | да | Окружение, из которого сливают |
| --into | да | Окружение, в которое сливают |
| --removals | нет | Удаляет также из цели то, чего больше нет в источнике |
| --select PATH | нет | Ограничивает слияние этим объектом по его пути в модели (metrics/revenue.yaml); повторите для других. То, что ему нужно и чего нет в цели, переносится вместе с ним и перечисляется (REQ-1506) |
[tool-verified: cli_envs.py:426-439]
provisa env merge¶
Сливает одно окружение в другое, по идентичности (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 | да | Окружение, из которого сливают |
| --into | да | Окружение, в которое сливают |
| --removals | нет | Удаляет также из цели то, чего больше нет в источнике |
| --select PATH | нет | Ограничивает слияние этим объектом по его пути в модели (metrics/revenue.yaml); повторите для других. То, что ему нужно и чего нет в цели, переносится вместе с ним и перечисляется (REQ-1506) |
| --dry-run | нет | Печатает отчёт о слиянии и ничего не применяет |
| --message | нет | Что делает слияние; обязательно для применения |
| --retire-source | нет | Удаляет источник, когда его работа попала в цель |
| --retire-remote | нет | С --retire-source удаляет также ветку источника на удалённом репозитории |
[tool-verified: cli_envs.py:429-451]
provisa env deploy¶
Развёртывает модель по ссылке git в окружение, делая это дерево текущей моделью окружения (REQ-1496). Это команда, которую запускает конвейер развёртывания; развёртывание — всегда вызов с идентичностью против названной плоскости управления. [tool-verified: cli_envs.py:253-267]
| Флаг | Обязательный | Примечания | | --- | --- | --- | |--env | да | Окружение, которое будет содержать развёрнутую модель |
| --ref | да | Ветка или коммит в репозитории организации |
| --dry-run | нет | Сообщает, что сделало бы развёртывание; ничего не применяет |
| --message | нет | Заметка, переносимая в запрос на одобрение, когда цель защищена |
[tool-verified: cli_envs.py:453-468]
Загрузка в существующее окружение никогда не применяет роли. --seed больше нет: API отклоняет seed
с 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¶
Возвращает окружение к предыдущей сборке (REQ-1543). Без --to отступает на один коммит
в собственной истории окружения. С --to это обычное развёртывание этой сборки.
[tool-verified: cli_envs.py:270-284]
--env | да | Окружение для возврата |
| --to | нет | Сборка для развёртывания; по умолчанию предшествующая текущей |
| --message | нет | Заметка, переносимая в запрос на одобрение |
[tool-verified: cli_envs.py:470-480]
provisa env redo¶
Снова идёт вперёд к сборке, от которой ушёл возврат. [tool-verified: cli_envs.py:287-301]
provisa env fetch¶
Получает удалённые ветки организации в её репозиторий Provisa (REQ-1541). Запускайте перед развёртыванием,
когда хотите указать origin/<branch>. Provisa никогда не запускает его по таймеру. [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¶
Отправляет ветку окружения в удалённый репозиторий организации (REQ-1546). Печатает nothing to send, когда
отправлять нечего. [tool-verified: cli_envs.py:323-331]
provisa env pull¶
Применяет то, что удалённый репозиторий содержит для окружения (REQ-1547). Печатает
<env> already holds what the remote does, когда применять нечего. Код выхода 2 действует так же,
как для deploy. [tool-verified: cli_envs.py:334-343]
provisa maintenance on¶
Поднять баннер запланированного обслуживания на развёртывании (REQ-1466). Выполните это перед плановыми
работами, которые останавливают плоскость данных — например, перед изменением
var.engine_cluster_mode, что заменяет кластер движка и каждый его шард (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]
| Флаг | Примечания |
|---|---|
--message |
Переопределить стандартную формулировку развёртывания; по умолчанию — стандартное сообщение сервера |
--ends-at |
Момент в формате ISO-8601, к которому ожидается завершение работ, например 2026-08-14T22:30:00Z; по умолчанию оценка отсутствует |
--api |
См. Общие параметры |
--token |
Bearer-токен для идентификации, обладающей platform_settings |
--timeout |
По умолчанию 30 с |
[tool-verified: cli.py:743-773]
Выводит итоговое состояние баннера и завершается с кодом 0. Вызывает SystemExit при сбое HTTP или подключения.
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¶
Очистить баннер обслуживания по завершении работ (REQ-1466).
[tool-verified: _cmd_maintenance_off() at cli.py:498-501]
Выводит итоговое состояние баннера (active: false) и завершается с кодом 0.
provisa maintenance off --api "$PROVISA_API_URL" --token "$PROVISA_API_TOKEN"
# Maintenance notice: OFF
provisa maintenance status¶
Показать текущее состояние баннера обслуживания, не изменяя его (REQ-1466).
Выводит состояние баннера и завершается с кодом 0.
Maintenance notice: ON
Message: Engine cluster rolling upgrade
Since: 2026-09-22T01:15:00Z
Ends at: 2026-09-22T03:00:00Z
Краткий справочник¶
| Команда | REQ | Что делает |
|---|---|---|
provisa run |
REQ-1128 | Запустить встроенные API + интерфейс |
provisa run --demo |
REQ-414 | Запустить с примерами данных pet-store / shelter |
provisa run --reset |
REQ-1535 | Пересобрать плоскость управления перед запуском |
provisa license apply <file> |
REQ-1139 | Установить файл лицензии офлайн |
provisa license status |
REQ-1139 | Показать идентификатор машины и состояние пробного периода / лицензии |
provisa metadata export |
REQ-1072 | Опубликовать снимок метаданных по требованию |
provisa env list --org ORG |
REQ-1498 | Перечисляет окружения организации и их сборки |
provisa env show --org ORG --env ENV |
REQ-1498 | Показывает одно окружение |
provisa env create --org ORG --env ENV --data-mode MODE |
REQ-1942 | Создаёт окружение из другого |
provisa env delete --org ORG --env ENV |
REQ-1498 | Выводит окружение из эксплуатации |
provisa env diff --org ORG --from A --into B |
REQ-1490 | Предпросмотр слияния (только чтение) |
provisa env merge --org ORG --from A --into B |
REQ-1490 | Сливает одно окружение в другое |
provisa env deploy --org ORG --env ENV --ref REF |
REQ-1496 | Развёртывает ссылку в окружение |
provisa env revert --org ORG --env ENV [--to BUILD] |
REQ-1543 | Отступает на один коммит или развёртывает сборку |
provisa env redo --org ORG --env ENV |
REQ-1543 | Снова идёт вперёд |
provisa env fetch --org ORG |
REQ-1541 | Получает удалённые ветки в репозиторий Provisa |
provisa env push --org ORG --env ENV |
REQ-1546 | Отправляет ветку окружения в удалённый репозиторий |
provisa env pull --org ORG --env ENV |
REQ-1547 | Применяет то, что содержит удалённый репозиторий |
provisa maintenance on |
REQ-1466 | Поднять баннер обслуживания |
provisa maintenance off |
REQ-1466 | Очистить баннер обслуживания |
provisa maintenance status |
REQ-1466 | Показать текущее состояние баннера |
См. также¶
- Окружения — модель окружений, защищённые окружения, жизненный цикл утверждения развёртывания
- Экспорт метаданных — провайдеры каталога, конфигурация и содержимое снимка
- Развёртывание — контейнерный уровень и облачное развёртывание