CLI

nrz — официальный CLI для разработки и деплоя на ONREZA Platform. Написан на Rust, включает локальный эмулятор платформенных API (KV, Context) и управление PostgreSQL.

LLM-First Design

CLI спроектирован для автономного использования LLM-агентами:

--json глобальный флаг (NRZ_JSON=1) — машинный вывод в stdout
--token глобальный флаг (NRZ_TOKEN) — аутентификация без device flow
--workspace глобальный флаг (NRZ_WORKSPACE) — выбор workspace
--environment у Environment-aware команд (NRZ_ENVIRONMENT) — явный контекст исполнения; nrz context use сохраняет контекст репозитория
JSON output: один объект в stdout, ошибки {"error": "..."}, exit code 1
Human output: цветной текст в stderr (по умолчанию)

Structured Log Streaming

В JSON-режиме (--json / NRZ_JSON=1) все команды CLI стримят структурированные log-строки — по одной JSON-строке на каждое сообщение о прогрессе:

{"s":"user","p":"install","l":"info","m":"Installing dependencies: npm install"}
{"s":"debug","p":"install","l":"info","m":"npm timing idealTree Completed in 243ms"}
{"s":"user","p":"build","l":"info","m":"✓ Build completed"}

Ключ	Значение	Описание
`s`	`user` / `debug`	Целевой стрим: `user` — для пользователя, `debug` — внутренний вывод
`p`	`auth` / `build` / `db` / `deploy` / `detect` / `domains` / `env` / `init` / `install` / `link` / `projects` / `rollback` / `workspace`	Фаза операции
`l`	`info` / `warn` / `error`	Уровень сообщения
`m`	string	Текст сообщения

Фильтрация user-строк с jq:

NRZ_JSON=1 nrz deploy 2>/dev/null | jq -r 'select(.s=="user") | .m'

Подробнее: JSON Output

Установка

Quick Install

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/ONREZA/nrz-cli/main/install.sh | bash

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/ONREZA/nrz-cli/main/install.ps1 | iex

Через пакетный менеджер

npm i -g @onreza/nrz
# или
pnpm i -g @onreza/nrz
# или
bun i -g @onreza/nrz

Скачать вручную

Скачайте бинарник для вашей платформы из GitHub Releases:

nrz-linux-x64 — Linux x86_64
nrz-macos-x64 — macOS Intel
nrz-macos-arm64 — macOS Apple Silicon
nrz-windows-x64.exe — Windows x86_64

Глобальные флаги

Все команды поддерживают следующие глобальные флаги:

Флаг	Переменная окружения	Описание
`--json`	`NRZ_JSON=1`	Машиночитаемый JSON вывод
`--token <token>`	`NRZ_TOKEN`	API токен для аутентификации
`--workspace <slug>`	`NRZ_WORKSPACE`	Workspace slug

Environment не является глобальным флагом. Команды, которым нужен контекст, принимают --environment <name-or-id> и используют NRZ_ENVIRONMENT либо gitignored repository context из nrz context use <name-or-id>.

Команды

nrz init

Инициализирует проект: создаёт onreza.toml, определяет фреймворк, опционально создаёт проект на платформе.

nrz init [OPTIONS]

Флаг	Описание
`--name <name>`	Имя проекта (по умолчанию: имя директории)
`--skip-detection`	Пропустить автоопределение фреймворка
`--create`	Создать проект на платформе
`--project-id <id>`	Привязать существующий проект по ID

# Интерактивная инициализация
nrz init

# Создать проект на платформе
nrz init --create --name my-project

# Привязать существующий проект
nrz init --project-id proj_abc123

nrz link

Привязывает текущую директорию к проекту на платформе.

nrz link [dir] [OPTIONS]

Флаг	Описание
`dir`	Путь к директории проекта (по умолчанию: `.`)
`--project-id <id>`	ID проекта (пропустить интерактивный выбор)

# Интерактивный выбор проекта
nrz link

# Привязка по ID
nrz link --project-id proj_abc123

nrz dev

Запускает локальный dev-сервер с эмуляцией платформенных API.

nrz dev [dir] [OPTIONS]

Флаг	Описание
`dir`	Путь к директории проекта (по умолчанию: `.`)
`--alias <name>`	Запустить алиас из `[dev.aliases]` в onreza.toml
`--command <cmd>`	Команда запуска (переопределяет конфиг)
`--port`, `-p <port>`	Порт dev-сервера (по умолчанию: 4321)
`--inspect`	Включить Node.js inspector (порт 9229)
`--inspect-brk`	Включить inspector с остановкой на старте
`--db-branch <name>`	Ветка управляемого PostgreSQL для подключения

# Автодетект фреймворка
nrz dev

# Использовать алиас
nrz dev --alias staging

# Другой порт + inspector
nrz dev --port 3000 --inspect

nrz build

Валидирует build output и манифест проекта.

nrz build [dir] [OPTIONS]

Флаг	Описание
`dir`	Путь к директории проекта (по умолчанию: `.`)
`--skip-validation`	Пропустить валидацию манифеста

nrz build
nrz build ./my-app --skip-validation

nrz deploy

Деплоит проект на платформу ONREZA.

nrz deploy [dir] [OPTIONS]

Флаг	Описание
`dir`	Путь к директории проекта (по умолчанию: `.`)
`--environment <name-or-id>`	Окружение по точному имени или ID
`--prod`	Выбрать окружение `production`; несовместим с `--environment`
`--project-id <id>`	ID проекта (пропустить автоопределение)
`--service-id <id>`	Выбрать конкретный Service; без флага используется default Service
`--skip-build`	Пропустить шаг сборки
`--build-command <cmd>`	Кастомная команда сборки
`--skip-env-check`	Пропустить проверку env переменных

# Деплой в выбранное окружение
nrz deploy

# Явно выбрать preview
nrz deploy --environment preview

# Production деплой
nrz deploy --prod

# С кастомной сборкой
nrz deploy --build-command "npm run build:staging"

Без --environment или --prod CLI использует NRZ_ENVIRONMENT либо контекст, сохранённый через nrz context use. Если окружение не выбрано, команда завершится ошибкой. Адрес приложения принадлежит окружению и сохраняется при смене релиза. Если платформенный адрес отключён или отсутствует, URL в результате может быть null. Private-only окружению публичный адрес не требуется.

nrz services

Service имеет собственный Source, source ref и корень проекта. Список Services также показывает доступные Sources, поэтому их ID можно получить из команды. Создание отдельного CLI Source не меняет Sources соседних Services.

nrz services list --project-id <product-id> --json
nrz services create-source --project-id <product-id> --json
nrz services create-source --project-id <product-id> --git-url https://github.com/example/api --json
nrz services create --project-id <product-id> --name api --source-id <source-id> --source-ref main --root-directory services/api
nrz services update <service-id> --project-id <product-id> --name api --source-id <source-id> --source-ref release --root-directory services/api
nrz deploy ./services/api --project-id <product-id> --service-id <service-id> --environment production
nrz services delete <service-id> --project-id <product-id> --force

create и update задают полную конфигурацию Source. Удаление Service сохраняет БД и KV Product; если runtime ещё используется, ответ сообщает ожидающее удаления состояние. В панели те же операции доступны через выбор Service и Source.

nrz deploy-set

Выбранные Services переключаются одной заявкой. Версии остальных Services берутся из последнего принятого состава окружения; незавершённая предыдущая заявка отменяется. Новый состав не переключается, пока не подготовлены все выбранные Services.

# Все Services с Git Sources
nrz deploy-set --project-id <product-id> --environment production --all

# Два выбранных Service
nrz deploy-set --project-id <product-id> --environment production --service-id <web-id> --service-id <api-id>

# Смешанный состав: локальный Source и Git Sources
nrz deploy-set --project-id <product-id> --environment production --all --local <api-id>=./api

Для каждого выбранного локального Source требуется --local <service-id>=<checkout>. Git Sources без локального пути собираются платформой. Команда публикует выбранные локальные Sources и ждёт результат одной общей заявки. При неизвестном результате повторите команду с выведенным --idempotency-key: сохранённый receipt удерживает исходные версии и поколение окружения. Не создавайте новый ключ для такого повтора. В панели можно выбрать один или несколько Git Services либо все Git Services; набор с локальными Sources отправляется через CLI.

nrz endpoints

Работа с частными endpoints выбранного Service и окружения:

nrz endpoints --project-id <product-id> --service-id <service-id> --environment-id <environment-id> list --json

Ответ содержит endpoint, разрешённых callers, доступные exports и текущие поколения настроек. Изменяющие команды export, import, network и exposure требуют ожидаемое поколение; stale ответ нужно перечитать, а не перезаписывать. network --file network.json принимает полный network-контракт. Для exposure <layer> public обязателен файл --public-route-preview. Для связи Products нужны export provider и import caller в одном окружении Workspace; доступ к одному Product не даёт права изменить другой.

nrz projects

Управление проектами.

nrz projects <subcommand>

Субкоманда	Описание
`list [--limit <n>]`	Список проектов
`create --name <name>`	Создать проект
`info <id>`	Информация о проекте
`update <id>`	Обновить настройки проекта
`delete <id>`	Удалить проект

Create флаги:

Флаг	Описание
`--name <name>`	Обязательно — имя проекта
`--display-name <name>`	Отображаемое имя
`--git-url <url>`	URL Git репозитория
`--branch <branch>`	Git ветка (по умолчанию: main)
`--framework <fw>`	Фреймворк (astro, nuxt, sveltekit, nitro)
`--install-command <cmd>`	Команда установки зависимостей
`--build-command <cmd>`	Команда сборки
`--output-directory <dir>`	Директория сборки
`--link`	Привязать к текущей директории

Delete флаги:

Флаг	Описание
`id`	Обязательно — ID проекта
`--force`	Пропустить подтверждение

Update флаги:

Флаг	Описание
`--display-name <name>`	Отображаемое имя
`--git-url <url>`	URL Git репозитория
`--branch <branch>`	Git ветка
`--framework <fw>`	Фреймворк
`--install-command <cmd>`	Команда установки
`--build-command <cmd>`	Команда сборки
`--output-directory <dir>`	Директория сборки
`--root-directory <dir>`	Корневая директория
`--node-version <ver>`	Версия Node.js

# Список проектов
nrz projects list

# Создать и привязать
nrz projects create --name my-app --framework astro --link

# Информация
nrz projects info proj_abc123

# Обновить
nrz projects update proj_abc123 --build-command "npm run build"

# Удалить
nrz projects delete proj_abc123 --force

nrz deployments

Список деплоев проекта.

nrz deployments [OPTIONS]

Флаг	Описание
`--limit <n>`	Максимальное количество (по умолчанию: 10)
`--project-id <id>`	ID проекта

nrz deployments
nrz deployments --limit 20

nrz logs

Просмотр runtime логов проекта.

nrz logs [OPTIONS]

Флаг	Описание
`--deployment-id <id>`	Фильтр по ID деплоя
`--project-id <id>`	ID проекта
`--limit <n>`	Количество записей (по умолчанию: 50)
`--search <query>`	Поисковый запрос

nrz logs
nrz logs --search "error" --limit 100

nrz rollback

Активирует выбранный сохранённый релиз окружения с его приложением, Functions и Edge Rules. Новая сборка и новый деплой для отката не создаются.

nrz rollback [OPTIONS]

Флаг	Описание
`--release-id <id>`	ID сохранённого релиза для выборочного восстановления Service
`--composition-id <id>`	ID сохранённого полного состава окружения; несовместим с `--release-id`
`--service-id <id>`	Service для разрешения выбранного окружения
`--list`	Показать сохранённые релизы и полные составы окружения; несовместим с ID восстановления
`--environment <name-or-id>`	Окружение по точному имени или ID; иначе используется выбранный контекст
`--dir <path>`	Директория проекта с сохранённым контекстом (по умолчанию: `.`)
`--project-id <id>`	ID проекта

# Найти релиз для отката
nrz rollback --list --environment production

# Восстановить один Service, сохранив текущие версии соседей
nrz rollback --environment production --release-id 00000000-0000-4000-8000-000000000002

# Восстановить весь сохранённый состав Services
nrz rollback --environment production --composition-id 00000000-0000-4000-8000-000000000003

Команда возвращается после принятия заявки на активацию, не дожидаясь переключения трафика. В JSON-выводе operationId, releaseId и desiredGeneration идентифицируют принятую заявку; её status ещё не подтверждает завершение отката.

Проверить завершение можно через GET /v1/environments/{environmentId}/serving: desired.generation должен совпадать с полученным desiredGeneration, desired.activeEverywhere — быть true, а observed.releaseId — совпадать с выбранным релизом. При повторном --list фактически активный релиз отмечается как observed active. Адрес окружения при откате сохраняется, если он существует; в private-only окружении address в Serving равен null. Это не мешает восстановлению.

При --list ответ содержит отдельные cursors для релизов и полных составов. Для следующей страницы передайте обе части соответствующего cursor: --before-created-at с --before-release-id либо --before-composition-created-at с --before-composition-id.

nrz db

Управление базами управляемого PostgreSQL.

nrz db <subcommand> [OPTIONS]

Глобальный флаг --project-id <id> доступен для всех субкоманд.

Субкоманда	Описание
`list`	Список баз данных проекта
`create`	Создать новую базу данных
`info [database]`	Информация о БД
`delete <database>`	Удалить базу данных
`start [database]`	Запустить остановленную БД
`stop [database]`	Остановить БД
`connection [database]`	Строка подключения
`query [sql]`	Выполнить SQL запрос
`schema [database]`	Показать структуру БД (таблицы, колонки)
`branches`	Управление ветками БД
`config [database]`	Настройки auto-inject

Если [database] не указан — используется значение из [db] database в onreza.toml, или первая БД с включённым auto-inject.

Create флаги:

Флаг	Описание
`--name <name>`	Имя базы данных
`--cu-size <size>`	Размер CU (0.25, 0.5, 1.0, 2.0, 4.0, 8.0)
`--wait`	Дождаться активации перед возвратом

Query флаги:

Флаг	Описание
`sql`	SQL запрос
`--file <path>`	Прочитать SQL из файла
`--database <id>`	ID или имя БД
`--branch <name>`	Ветка БД для выполнения

Connection флаги:

Флаг	Описание
`--branch <name>`	Получить строку подключения ветки

Branches субкоманды:

Субкоманда	Описание
`branches`	Список веток (по умолчанию)
`branches create <name>`	Создать ветку
`branches delete <branch>`	Удалить ветку
`branches connection <branch>`	Строка подключения ветки

Config флаги:

Флаг	Описание
`--auto-inject <true\|false>`	Включить/выключить auto-inject DATABASE_URL
`--env-var <NAME>`	Имя переменной для auto-inject
`--preview-branches <true\|false>`	Автосоздание веток для preview-деплоев

# Список баз данных
nrz db list

# Создать БД и дождаться активации
nrz db create --name my-app-db --wait

# Информация
nrz db info

# Строка подключения
nrz db connection
nrz db connection --branch dev

# Выполнить SQL
nrz db query "SELECT * FROM users LIMIT 10"
nrz db query --file ./query.sql --branch staging

# Структура БД (для LLM-агентов)
nrz db schema --json

# Управление ветками
nrz db branches
nrz db branches create feature-auth
nrz db branches delete feature-auth

# Настройки auto-inject
nrz db config --auto-inject true --env-var DATABASE_URL --preview-branches true

# Остановить / запустить
nrz db stop
nrz db start

# Удалить (требует --force в non-interactive режиме)
nrz db delete my-app-db --force

nrz kv

Управление локальным KV-хранилищем.

nrz kv <subcommand>

Субкоманда	Описание
`get <key>`	Получить значение
`set <key> <value>`	Установить значение
`remove <key>`	Удалить ключ
`list [--prefix <p>] [--limit <n>]`	Список ключей
`clear [--force]`	Очистить все данные

# Установить значение
nrz kv set user:123 '{"name": "John"}'

# С TTL (1 час)
nrz kv set session:abc token123 --ttl 3600

# Получить
nrz kv get user:123

# Список с префиксом
nrz kv list --prefix user: --limit 50

# Удалить
nrz kv remove user:123

# Очистить
nrz kv clear --force

nrz env

Управление переменными окружения проекта.

nrz env <subcommand>

Субкоманда	Описание
`list`	Список переменных
`set <key>`	Установить переменную из безопасного input
`delete <key>`	Удалить project-wide definition
`validate`	Проверить по декларациям в onreza.toml
`exec -- <command>`	Запустить команду с эфемерно materialized context

Set флаги:

Флаг	Описание
`--value <value>`	Plain value; не использовать для секретов из-за shell history
`--stdin` / `--from-file <path>`	Безопасный input, обязательный для secret
`--plain` / `--secret`	Категория, если она не задана декларацией
`--environment <name-or-id>` / `--all`	Exact scope
`--replace-scope`	Явно разрешить изменение существующего scope
`--change-category`	Явно разрешить plain/secret conversion

# Список
nrz env list

# Установить plain и secret
nrz env set API_URL --value https://api.example.com --plain --environment preview
printf %s "$API_KEY" | nrz env set API_KEY --stdin --secret --environment preview

# Удалить единственную project-wide definition
nrz env delete API_URL --all

# Выполнить локально без записи plaintext dotenv
nrz env exec --environment preview -- npm run dev

# Валидация
nrz env validate --environment preview

nrz context

Управляет gitignored Environment context текущего checkout:

nrz context use preview
nrz context show
nrz context clear

nrz domains

Управление custom domain hostname bindings проекта. Parent workspace domain zone создается или переиспользуется сервером автоматически.

nrz domains <subcommand>

Флаг	Описание
`--project-id <id>`	ID проекта (пропустить автоопределение)
`--service-id <id>`	Выбрать конкретный Service; без флага используется default Service

Субкоманда	Описание
`list`	Список hostname bindings проекта
`add <domain>`	Привязать hostname к окружению
`remove <domain_id>`	Удалить hostname binding
`verify <domain_id>`	Проверить parent workspace domain zone

Add флаги:

Флаг	Описание
`--environment <name-or-id>`	Exact Environment; иначе используется сохранённый context

nrz domains list
nrz domains add example.com
nrz domains verify dom_abc123
nrz domains remove dom_abc123

nrz workspace

Управление workspaces.

nrz workspace <subcommand>

Субкоманда	Описание
`list`	Список workspaces
`switch <slug>`	Переключить default workspace

nrz workspace list
nrz workspace switch my-team

Аутентификация через OAuth 2.0 Device Flow.

nrz login

Команда автоматически:

Создаёт device flow запрос
Открывает браузер с URL для подтверждения
Ожидает подтверждения пользователя
Сохраняет токен в ~/.config/nrz/credentials.json

nrz logout

Выход из платформы.

nrz logout [OPTIONS]

Флаг	Описание
`--all`	Выйти из всех workspaces

nrz logout
nrz logout --all

nrz whoami

Информация о текущем пользователе.

nrz whoami

nrz upgrade

Обновление CLI до последней версии.

nrz upgrade [OPTIONS]

Флаг	Описание
`--force`	Обновить даже если уже последняя версия
`--version <tag>`	Конкретная версия (например, `v0.1.5`)

nrz upgrade
nrz upgrade --version v0.1.5

Конфигурация onreza.toml

onreza.toml — единый конфиг проекта, коммитится в git.

#:schema https://raw.githubusercontent.com/onreza/nrz-cli/main/onreza.schema.json

[project]
id = "proj_abc123"
name = "my-project"
workspace = "my-team"

[dev]
command = "npm run dev"
port = 4321
host = "127.0.0.1"
data_dir = ".onreza/data"

[dev.aliases]
network = "npm run dev -- --host 0.0.0.0"
staging = "npm run dev -- --host 0.0.0.0 --port 3001"

[build]
command = "npm run build"
output_dirs = ["dist", ".output", "build"]

[db]
# database = "my-db"   # ID или имя базы PostgreSQL (определяется автоматически, если не указано)
# branch = "dev"       # Ветка для nrz dev (main если не указано)

[env]
[env.declarations]
DATABASE_URL = "sensitive"
PUBLIC_API_URL = "plain"
OPTIONAL_VAR = { visibility = "plain", required = false }

Секция `[env]`

Декларирует переменные окружения проекта:

Строка "sensitive" / "plain" — shorthand, переменная обязательна
Table { visibility = "...", required = false } — для необязательных переменных

Используется в:

nrz env set — определяет plain/secret category, если флаг не передан
nrz env validate — проверяет required переменные
nrz deploy — pre-flight проверка перед деплоем

CI/CD

Для использования в CI/CD передайте токен через переменную окружения:

export NRZ_TOKEN="nrz_xxx"
nrz deploy --prod

Пример для GitHub Actions:

- name: Deploy to ONREZA
  env:
    NRZ_TOKEN: ${{ secrets.ONREZA_TOKEN }}
  run: |
    nrz deploy --prod

Device Flow API

OAuth 2.0 Device Authorization Grant (RFC 8628) — механизм аутентификации CLI.

Инициация

POST /v1/device

Ответ:

{
  "device_code": "abc123def456...",
  "user_code": "ABCD-1234",
  "verification_uri": "https://app.onreza.ru/device",
  "verification_uri_complete": "https://app.onreza.ru/device?code=ABCD-1234",
  "expires_in": 300,
  "interval": 5
}

Получение токена

POST /v1/device/token

Успешный ответ (200):

{
  "access_token": "nrz_xxxxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "workspace_slug": "my-workspace",
  "workspace_name": "My Workspace"
}

Ошибки:

Статус	Ошибка	Описание
400	`authorization_pending`	Пользователь ещё не подтвердил
400	`slow_down`	Слишком частый polling
400	`expired_token`	Device code истёк
400	`invalid_grant`	Device code не найден

Коды ошибок API

Код	Описание
200	Успешный запрос
400	Некорректный запрос
401	Не авторизован
403	Доступ запрещён
404	Ресурс не найден
409	Конфликт (например, параллельный деплой)
429	Rate limit

Rate Limits

Endpoint	Limit
`/v1/device`	10 запросов/минуту с одного IP
`/v1/device/token`	Polling с интервалом из поля `interval` (5 c); при слишком частых запросах возвращается `slow_down`
API с аутентификацией по API key	5000 запросов/час на ключ

При превышении лимита возвращается статус 429 с заголовком Retry-After.