CLI

nrz — официальный CLI для разработки и деплоя на платформе ONREZA. Написан на Rust, включает локальный эмулятор платформенных API (KV, Context) и управление managed 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 warn deprecated inflight@1.0.6"}
{"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>`	Ветка managed 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`	Путь к директории проекта (по умолчанию: `.`)
`--prod`	Production деплой
`--project-id <id>`	ID проекта (пропустить автоопределение)
`--skip-build`	Пропустить шаг сборки
`--build-command <cmd>`	Кастомная команда сборки
`--skip-env-check`	Пропустить проверку env переменных

# Деплой preview
nrz deploy

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

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

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

Откат к предыдущему деплою.

nrz rollback [OPTIONS]

Флаг	Описание
`--deployment-id <id>`	ID деплоя для отката (по умолчанию: текущий live)
`--project-id <id>`	ID проекта

nrz rollback
nrz rollback --deployment-id dep_xyz789

nrz db

Управление managed 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 Store.

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 проекта (пропустить автоопределение)

Субкоманда	Описание
`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 или имя managed PostgreSQL (auto-resolved если не указано)
# 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.