Справочник CLI¶

Команда provisa является единственной точкой входа во встроенный уровень, установленный через pip. Она запускает среду выполнения, управляет лицензиями, запускает публикацию метаданных, развёртывает модели и управляет баннером обслуживания. Вам не нужны ни Docker, ни Node, ни внешние сервисы.

Установите её с дополнительным пакетом embedded, который также подтягивает офлайн-расширения DuckDB и встроенную плоскость управления PostgreSQL:

pip install 'provisa[embedded]'

Требования к платформе. provisa run требует Python 3.12 и платформу с колесом (wheel) pgserver: linux x86_64, macOS или Windows x86_64. У Linux aarch64 нет ни колеса pgserver, ни исходного дистрибутива, поэтому встраиваемый уровень там не работает. Используйте контейнерный уровень на aarch64.

Общие параметры¶

Несколько подкоманд вызывают HTTP API Provisa. Они разделяют три флага и две переменные окружения.

Флаг	По умолчанию	Резервная переменная окружения
`--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 не отправляется, и именно этого ждёт развёртывание без аутентификации.

Задайте обе переменные в вашем окружении CI, чтобы не повторять их при каждом вызове:

export PROVISA_API_URL=https://acme.provisa.org
export PROVISA_API_TOKEN=<token>

Подкоманды, принимающие эти флаги: 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 и внешние сервисы не участвуют.

provisa run [--demo] [--host HOST] [--api-port PORT] [--ui-port PORT]
            [--no-browser] [--reset] [--data-dir DIR]

Флаги¶

Флаг	По умолчанию	Примечания
`--demo`	выкл	Загрузить встроенную демонстрацию — примеры доменов pet-store и shelter поверх встроенного SQLite
`--host`	`127.0.0.1`	Адрес привязки для обоих серверов
`--api-port`	`8000`	Порт API-сервера
`--ui-port`	`3000`	Порт статического/прокси-сервера интерфейса
`--no-browser`	выкл	Пропустить открытие браузера при готовности интерфейса; URL всё равно выводится
`--reset`	выкл	Удалить и пересоздать хранилище встроенной плоскости управления перед запуском; используйте после обновления Provisa, если запуск сообщает о несоответствии схемы
`--data-dir`	`~/.provisa/native`	Каталог, содержащий встроенный кластер PostgreSQL и кеш расширений DuckDB

Переменные окружения¶

provisa run читает несколько дополнительных переменных перед запуском HTTP-серверов. Задайте их, чтобы переопределить значения по умолчанию, которые иначе применил бы load_profile("native", ...).

Переменная	Эффект
`TRINO_HOST` / `TRINO_PORT`	Заменяет встроенный движок DuckDB на предоставленный клиентом координатор Trino
`PROVISA_ENGINE_URL`	Альтернативный способ указать на внешний федеративный движок
`PROVISA_CONFIG`	Файл конфигурации для загрузки; `--demo` устанавливает его во встроенную демонстрационную конфигурацию
`PROVISA_DEMO`	Устанавливается в `1` флагом `--demo`; помечает сессию как демонстрационный запуск
`PROVISA_DEMO_DIR`	Путь к каталогу примеров данных для демонстрации; устанавливается флагом `--demo`
`PROVISA_DUCKDB_EXT_DIR`	Заранее подготовленный каталог расширений DuckDB; устанавливается автоматически из пакета `provisa-duckdb-ext`, если он присутствует; отсутствие означает, что DuckDB загрузится из сети при первом использовании

Последовательность запуска¶

Проверка платформы — прерывает работу с понятным сообщением при неподдерживаемом Python или отсутствующем pgserver.
--reset (если запрошен) — удаляет встроенный кластер PostgreSQL; он пересоздаётся на следующем шаге.
Демонстрационная конфигурация (если --demo) — устанавливает PROVISA_CONFIG и PROVISA_DEMO_DIR.
Встроенное окружение — запускает плоскость управления PostgreSQL, разрешает её URL сокета и подготавливает офлайн-расширения DuckDB, если установлен provisa-duckdb-ext.
Проверка расхождения схемы — сканирует действующую плоскость управления на предмет отсутствующих столбцов. Если такие найдены, выводится подсказка о --reset, и работа завершается с кодом 1. В V1 нет миграций; столбец, добавленный в более новом релизе, требует сброса.
Оба сервера запускаются одновременно. Индикатор готовности опрашивает GET /ready (не /health, потому что конечная точка /ready подтверждает, что хранилище подключено и движок прогрет) и открывает браузер, когда получает 200.

Коды завершения¶

Код	Значение
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¶

Проверить и установить файл лицензии офлайн. Файл — это license.json, выданный provisa.dev.

provisa license apply <file>

Аргумент	Примечания
`file`	Путь к файлу лицензии; применяется раскрытие `~`

Код завершения 0 означает, что лицензия действительна и установлена. Код завершения 1 означает, что она была отклонена; причина выводится в stderr.

provisa license apply ~/Downloads/license.json

provisa license status¶

Показать идентификатор машины, состояние пробного периода, прошедшие дни и действительность лицензии.

provisa license status

Флагов нет. Выводит пять строк (ID машины, дата первого появления, прошедшие дни, состояние пробного периода и состояние лицензии) и завершается с кодом 0.

Machine ID:   a1b2c3d4e5f6...
First seen:   2026-07-01
Elapsed:      83.0 days
Trial:        active
Licensed:     no (no license installed)

provisa metadata export¶

Запускает публикацию метаданных по запросу на работающем сервере. Команда отправляет запрос на POST /admin/metadata-export/publish, ту же конечную точку, которую вызывает кнопка Publish now на вкладке Admin, поэтому оба пути отправляют один и тот же полный снимок.

provisa metadata export [--api URL] [--token TOKEN] [--timeout SECONDS]

Флаг	По умолчанию	Примечания
`--api`	`$PROVISA_API_URL`, затем `http://127.0.0.1:8000`	В условиях многоарендности имя хоста называет организацию
`--token`	`$PROVISA_API_TOKEN`	Bearer-токен для идентификации, обладающей `org_settings`; опустите на неавторизованных развёртываниях
`--timeout`	`300`	Секунды до отмены HTTP-вызова

Код завершения	Значение
0	Все активы опубликованы
1	Частичная публикация или сбой подключения; ошибки по каждому активу выводятся в stderr

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. Каждая подкоманда — это вызов API администратора, который вызывает интерфейс; CLI ничего не решает. Список того, что переносит копия, правила слияния и удаления, привязка, защита и права вызывающего принадлежат серверу, поэтому действуют независимо от того, как вызвана операция.

provisa env {list,show,create,delete,diff,merge,deploy,revert,redo,fetch,push,pull} --org ORG ...

Флаги, которые принимает каждая подкоманда¶

Флаг	Обязательный	Примечания
`--org`	да	Организация, которой принадлежит окружение
`--json`	нет	Печатает ответ API как JSON, для скрипта
`--api`	нет	См. Общие параметры
`--token`	нет	Bearer-токен идентичности, которой разрешена операция
`--timeout`	нет	Секунды; по умолчанию 300

Подкоманды, действующие на одно окружение, также принимают --env ENV (обязательно). list, diff, merge и fetch — нет; diff и merge называют свои окружения через --from и --into.

Коды выхода¶

Код	Значение
0	Готово, или пробный запуск, который ничего не применил
1	Отклонено. Код отклонившего правила печатается в stderr как `refused (<code>): <detail>`; с `--json` это `{"refused": {...}}` в stdout
2	Предложено, не применено: целевое окружение защищено, и изменение ждёт одобрения

Код выхода 2 намеренный. Конвейер, который считал бы ожидающее одобрение выпущенным развёртыванием, ошибался бы.

provisa env list¶

Перечисляет окружения организации и сборку, на которой находится каждое. Никаких флагов, кроме общих.

provisa env list --org ORG [--json]

provisa env show¶

Показывает одно окружение и его текущую сборку. Завершается с 1 и environments.unknown, если окружение не существует.

provisa env show --org ORG --env ENV [--json]

provisa env create¶

Создаёт окружение, содержащее модель другого, с данными, выбранными при создании. API решает, какой выбор может сделать вызывающий.

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`: подключения окружения `--from`, скопированные в том виде, в каком они там записаны, никаких, пока оно не привяжет свои, или тестовые данные
`--mutation-handling`	нет	`refused`, `reversible` или `direct`; по умолчанию `refused`
`--expires-at`	нет	Момент ISO-8601, после которого окружение удаляется

provisa env create --org acme --env feature-x --from prod --data-mode test_fake

provisa env delete¶

Выводит окружение из эксплуатации. Его ветки удаляются, только если названы.

provisa env delete --org ORG --env ENV [--delete-branch] [--delete-remote-branch]

Флаг	Примечания
`--delete-branch`	Удаляет также его ветку
`--delete-remote-branch`	Удаляет также его ветку на удалённом репозитории

provisa env diff¶

Сообщает, что сделало бы слияние одного окружения в другое. Это GET merge-preview, поэтому он не может писать; отдайте его раннеру, который не должен ничего менять.

provisa env diff --org ORG --from SOURCE --into TARGET [--removals] [--select PATH ...]

Флаг	Обязательный	Примечания
`--from`	да	Окружение, из которого сливают
`--into`	да	Окружение, в которое сливают
`--removals`	нет	Удаляет также из цели то, чего больше нет в источнике
`--select PATH`	нет	Ограничивает слияние этим объектом по его пути в модели (`metrics/revenue.yaml`); повторите для других. То, что ему нужно и чего нет в цели, переносится вместе с ним и перечисляется

provisa env merge¶

Сливает одно окружение в другое, по идентичности.

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`); повторите для других. То, что ему нужно и чего нет в цели, переносится вместе с ним и перечисляется
`--dry-run`	нет	Печатает отчёт о слиянии и ничего не применяет
`--message`	нет	Что делает слияние; обязательно для применения
`--retire-source`	нет	Удаляет источник, когда его работа попала в цель
`--retire-remote`	нет	С `--retire-source` удаляет также ветку источника на удалённом репозитории

provisa env deploy¶

Развёртывает модель по ссылке git в окружение, делая это дерево текущей моделью окружения . Это команда, которую запускает конвейер развёртывания; развёртывание — всегда вызов с идентичностью против названной плоскости управления.

provisa env deploy --org ORG --env ENV --ref REF [--dry-run] [--message MSG]

Флаг	Обязательный	Примечания
`--env`	да	Окружение, которое будет содержать развёрнутую модель
`--ref`	да	Ветка или коммит в репозитории организации
`--dry-run`	нет	Сообщает, что сделало бы развёртывание; ничего не применяет
`--message`	нет	Заметка, переносимая в запрос на одобрение, когда цель защищена

Загрузка в существующее окружение никогда не применяет роли. --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¶

Возвращает окружение к предыдущей сборке. Без --to отступает на один коммит в собственной истории окружения. С --to это обычное развёртывание этой сборки.

provisa env revert --org ORG --env ENV [--to BUILD] [--message MSG]

Флаг	Обязательный	Примечания
`--env`	да	Окружение для возврата
`--to`	нет	Сборка для развёртывания; по умолчанию предшествующая текущей
`--message`	нет	Заметка, переносимая в запрос на одобрение

provisa env redo¶

Снова идёт вперёд к сборке, от которой ушёл возврат.

provisa env redo --org ORG --env ENV

provisa env fetch¶

Получает удалённые ветки организации в её репозиторий Provisa. Запускайте перед развёртыванием, когда хотите указать origin/<branch>. Provisa никогда не запускает его по таймеру.

provisa env fetch --org ORG

Печатает по строке на полученную ветку, 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¶

Отправляет ветку окружения в удалённый репозиторий организации. Печатает nothing to send, когда отправлять нечего.

provisa env push --org ORG --env ENV

provisa env pull¶

Применяет то, что удалённый репозиторий содержит для окружения. Печатает <env> already holds what the remote does, когда применять нечего. Код выхода 2 действует так же, как для deploy.

provisa env pull --org ORG --env ENV

Полное объяснение классов окружений, правил защиты, отчётов о слиянии и жизненного цикла одобрений см. в разделе Окружения.

provisa maintenance on¶

Поднимает баннер плановых работ в развёртывании. Выполняйте это перед плановыми работами, которые останавливают плоскость данных. Пример: переключение var.engine_cluster_mode, которое заменяет кластер движка и каждый шард на нём.

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 с

Выводит итоговое состояние баннера и завершается с кодом 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¶

Очистить баннер обслуживания по завершении работ.

provisa maintenance off [--api URL] [--token TOKEN] [--timeout SECONDS]

Выводит итоговое состояние баннера (active: false) и завершается с кодом 0.

provisa maintenance off --api "$PROVISA_API_URL" --token "$PROVISA_API_TOKEN"
# Maintenance notice: OFF

provisa maintenance status¶

Показать текущее состояние баннера обслуживания, не изменяя его.

provisa maintenance status [--api URL] [--token TOKEN] [--timeout SECONDS]

Выводит состояние баннера и завершается с кодом 0.

Maintenance notice: ON
  Message:  Engine cluster rolling upgrade
  Since:    2026-09-22T01:15:00Z
  Ends at:  2026-09-22T03:00:00Z

Краткий справочник¶

Команда	Что делает
`provisa run`	Запустить встроенные API + интерфейс
`provisa run --demo`	Запустить с примерами данных pet-store / shelter
`provisa run --reset`	Пересобрать плоскость управления перед запуском
`provisa license apply <file>`	Установить файл лицензии офлайн
`provisa license status`	Показать идентификатор машины и состояние пробного периода / лицензии
`provisa metadata export`	Опубликовать снимок метаданных по требованию
`provisa env list --org ORG`	Перечисляет окружения организации и их сборки
`provisa env show --org ORG --env ENV`	Показывает одно окружение
`provisa env create --org ORG --env ENV --data-mode MODE`	Создаёт окружение из другого
`provisa env delete --org ORG --env ENV`	Выводит окружение из эксплуатации
`provisa env diff --org ORG --from A --into B`	Предпросмотр слияния (только чтение)
`provisa env merge --org ORG --from A --into B`	Сливает одно окружение в другое
`provisa env deploy --org ORG --env ENV --ref REF`	Развёртывает ссылку в окружение
`provisa env revert --org ORG --env ENV [--to BUILD]`	Отступает на один коммит или развёртывает сборку
`provisa env redo --org ORG --env ENV`	Снова идёт вперёд
`provisa env fetch --org ORG`	Получает удалённые ветки в репозиторий Provisa
`provisa env push --org ORG --env ENV`	Отправляет ветку окружения в удалённый репозиторий
`provisa env pull --org ORG --env ENV`	Применяет то, что содержит удалённый репозиторий
`provisa maintenance on`	Поднять баннер обслуживания
`provisa maintenance off`	Очистить баннер обслуживания
`provisa maintenance status`	Показать текущее состояние баннера

См. также¶

Окружения — модель окружений, защищённые окружения, жизненный цикл утверждения развёртывания
Экспорт метаданных — провайдеры каталога, конфигурация и содержимое снимка
Развёртывание — контейнерный уровень и облачное развёртывание