na — Neuroartist CLI

Командная строка для Neuroartist API Gateway: запуск генераций, управление балансом, просмотр активности, отладка из терминала.

Установка

npm (рекомендовано — нужен Node 20+)

npm install -g @neuroartist/cli
na --version

Curl-installer (без Node, единый бинарник)

curl -fsSL https://raw.githubusercontent.com/CroissanStudioDev/neuroartist-api-cli/main/install.sh | sh

Скрипт определит ОС/арку, скачает соответствующий .tar.gz из последнего релиза, распакует в ~/.neuroartist/bin/na, пропишет PATH в .zshrc/.bashrc/config.fish и снимет macOS quarantine.

Опции:

# Конкретная версия
curl -fsSL https://raw.githubusercontent.com/CroissanStudioDev/neuroartist-api-cli/main/install.sh | sh -s -- v0.1.1

# Кастомный install dir
curl -fsSL https://raw.githubusercontent.com/CroissanStudioDev/neuroartist-api-cli/main/install.sh | NEUROARTIST_INSTALL=/opt/na sh

Windows

Качай .zip из последнего релиза: https://github.com/CroissanStudioDev/neuroartist-api-cli/releases/latest

Распакуй и положи na.exe в любую папку из PATH.

Из исходников (для dev)

git clone https://github.com/CroissanStudioDev/neuroartist-api-cli.git
cd neuroartist-api-cli
bun install
bun run dev auth login           # запуск напрямую
bun link                         # сделать `na` глобально доступным

Самосборка standalone-бинарника

bun run build:bin                  # текущая ОС/архитектура
bun run build:darwin-arm64         # явный target
bun run build:all                  # все 5 платформ

Quick start

# 1. Авторизуйся (вставь API-ключ na_live_*)
na auth login

# 2. Проверь себя
na whoami         # alias `na auth whoami`
na balance

# 3. Посмотри каталог
na models list --search banana --limit 10
na models schema nano-banana-pro

# 4. Запусти генерацию и сохрани результат
na run nano-banana-pro -i prompt="кот в очках" -o ./out

# 5. Async-режим (если модель медленная)
na queue submit some-video-model -i prompt="..."
na queue stream  some-video-model <requestId>
na queue result  some-video-model <requestId> -o ./out

Конфигурация

Конфиг лежит в ~/.config/neuroartist/config.json (уважает XDG_CONFIG_HOME), права 0600. Структура:

{
  "defaultProfile": "default",
  "profiles": {
    "default": {
      "apiKey": "na_live_...",
      "baseUrl": "https://api.neuroartist.ru"
    },
    "staging": {
      "apiKey": "na_live_...",
      "baseUrl": "https://staging.neuroartist.ru"
    }
  }
}

Приоритет источников ключа и URL

1. CLI-флаги: --profile, --base-url
2. Env: NEUROARTIST_API_KEY, NEUROARTIST_API_URL, NEUROARTIST_PROFILE
3. Конфиг-файл (профиль)
4. Default: https://api.neuroartist.ru

Несколько окружений

na --profile staging auth login --base-url https://staging.neuroartist.ru
na --profile staging balance

Команды

na auth login                    Сохранить API-ключ (interactive paste)
na auth logout                   Удалить ключ для текущего профиля
na auth whoami                   Информация о текущем ключе
na auth status                   Список профилей

na models list                   Каталог (без auth)
na models get <id>               Детали модели
na models schema <id>            JSON-схема входов/выходов
na models estimate <id> -i …     Оценка стоимости

na run <model> -i k=v -o ./out   Sync-генерация + скачивание ассетов
na run <model> --no-wait         Только submit, без ожидания

na queue submit <model> -i …     Поставить в очередь
na queue status <model> <id>     Текущий статус
na queue result <model> <id>     Финальный результат
na queue stream <model> <id>     SSE прогресс в реальном времени
na queue cancel <model> <id>     Отменить

na balance                       Текущий баланс
na usage summary                 Агрегаты по окнам (5h/24h/7d/30d)
na usage by-model -w 24h         Расход по моделям
na usage by-key   -w 24h         Расход по API-ключам
na activity --limit 20           Последние генерации

na doctor                        Self-check (config + /health + /me)
na update [--check]              Self-update binary install (or hint for npm/dev)
na completion bash|zsh|fish      Print shell completion script (eval $(na completion zsh))

Shell completion

# bash
echo 'eval "$(na completion bash)"' >> ~/.bashrc

# zsh — eval inline
echo 'eval "$(na completion zsh)"' >> ~/.zshrc

# zsh — function file (faster startup):
na completion zsh > "${fpath[1]}/_na"

# fish
na completion fish > ~/.config/fish/completions/na.fish

После установки: na <TAB> дополняет subcommand (auth, models, ...), na auth <TAB> — child (login, logout, whoami, status).

Передача входных данных

Флаг -i, --input повторяемый. Автодетект типа:

-i prompt="кот"                  string
-i num_steps=20                  number
-i enabled=true                  boolean
-i image=@./photo.png            файл → data:image/png;base64,...
-i config=@./body.json           JSON-файл → объект
-i 'styles=["a","b"]'            JSON-литерал
-i nested.field=42               вложенный объект

Альтернатива — целиком JSON-файл:

na run some-model --input-file ./body.json

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

--profile <name>      Профиль из конфига
--base-url <url>      Override gateway URL
--json                Принудительно JSON envelope (auto в pipe / non-TTY / NEUROARTIST_JSON=1)
--debug               HTTP traffic в stderr
-q, --quiet           Заглушить informational-сообщения
-y, --yes             Non-interactive (никогда не спрашивает)
-v, --version         Версия

Output формат

• В TTY — pretty (таблицы, цвета, единицы)
• В pipe / --json / NEUROARTIST_JSON=1 / CI=true — JSON envelope (см. ниже)
• stdout — данные. stderr — прогресс/ошибки/info. Безопасно пайпить.
• Honors NO_COLOR=1 (kleur автоматически).

na models list --json | jq '.data.items[] | select(.priceRub < 50) | .modelId'
na balance --json | jq -r .data.balance

Agent-friendly контракт

na спроектирован для двойного использования — людьми из терминала и LLM-агентами через shell. Контракт:

Стабильный JSON envelope (schemaVersion: 1)

Успех:

{
  "ok": true,
  "schemaVersion": 1,
  "command": "balance",
  "data": { "userId": "...", "balance": 1234 },
  "next_actions": [
    { "command": "na usage summary", "description": "Inspect spend" },
    { "command": "na activity", "description": "Last generations" }
  ]
}

Ошибка:

{
  "ok": false,
  "schemaVersion": 1,
  "command": "balance",
  "error": {
    "code": "no_api_key",
    "message": "API key not configured…",
    "retryable": false,
    "hint": "Run `na auth login` or set NEUROARTIST_API_KEY.",
    "httpStatus": 401
  },
  "next_actions": [...]
}

Granular exit codes

na queue submit fooz -i prompt="..." --json
case $? in
  0) echo "ok" ;;
  3) na auth login ;;
  4) sleep 2 && retry ;;
  5) echo "duplicate" ;;
esac

Self-discovery — na commands --json

Машинно-читаемое дерево всех команд + аргументов + флагов. Агенту достаточно одного вызова, чтобы узнать контракт целиком, без скрейпинга --help.

na commands --json | jq '.data[] | select(.name | startswith("na queue"))'

NDJSON streaming

na queue stream <model> <id> --json отдаёт одну JSON-строку на каждый event (NDJSON, как kubectl get -w -o json).

na queue stream fooz $REQ --json | while read -r line; do
  stage=$(echo "$line" | jq -r '.stage // .status')
  [[ "$stage" == "completed" ]] && break
done

Принципы (что считаем гарантией)

1. stdout = данные (всегда машинно-парсится в --json). stderr = логи / прогресс. Можно безопасно пайпить.
2. Wait > poll — na run --wait (default) блокируется до завершения, агенту не нужно крутить status в цикле.
3. --yes / CI=true — никогда не блокируется на интерактивных prompt'ах.
4. -q, --quiet — для скриптов, заглушает все non-data сообщения.
5. Named параметры — для опций, агенты не путают порядок.
6. --debug — печатает HTTP traffic в stderr, не загрязняет stdout.
7. Идемпотентность — na auth login --token X и na auth logout идемпотентны; na queue submit — нет (создаёт новый requestId), агент должен учитывать.

Что НЕ ломаем без bump'а schemaVersion

• Поля envelope: ok, schemaVersion, command, data, error, next_actions, warnings.
• Семантика exit codes 0/2/3/4/5.
• Имена команд (na auth login, na run, na queue submit, etc).
• Примеры в --help могут меняться, но описания и параметры — стабильно.

Меняем — новый schemaVersion, или новые опциональные поля. Строгая стабильность — обещание.

Архитектура

src/
  index.ts              entry, регистрация команд, error-handling
  version.ts
  config.ts             ~/.config/neuroartist/config.json + chmod 0600
  client.ts             fetch-обёртка с auth, retries, ApiError
  sse.ts                SSE-парсер для /progress/stream
  inputs.ts             -i key=val парсер с @file и dotted-path
  download.ts           collectUrls + downloadUrls для ассетов
  output.ts             pretty/json/table рендереры
  commands/
    auth.ts             login / logout / whoami / status
    models.ts           list / get / schema / estimate
    balance.ts          текущий баланс
    run.ts              sync run с --wait + asset download
    queue.ts            submit / status / result / stream / cancel
    usage.ts            summary / by-model / by-key + activity
    doctor.ts           диагностика

Разработка

bun run dev auth login           # запуск напрямую
bun run typecheck                # проверка типов
bun run check                    # ultracite check (без правок)
bun run fix                      # ultracite fix (auto-fix)
bun run build                    # JS-бандл (для npm)
bun run build:bin                # одиночный бинарник

Lint stack — Ultracite 7 (Biome 2)

biome.jsonc extends ultracite/biome/core. Локальные overrides:

• noConsole: off — CLI пишет в stdout/stderr намеренно
• noProcessEnv: off — env-vars часть контракта CLI

Парный с web (ultracite/biome/core + next + react). Backend на тех же Biome 2.4 + Ultracite 7, но с большим набором отключённых правил под legacy-код.

Pre-commit hook

husky 9 + lint-staged 15 сконфигурированы. Автоактивируются при git init + bun install:

• .husky/pre-commit → bunx lint-staged
• lint-staged запускает ultracite fix на staged .ts/.tsx/biome.jsonc/package.json

Если cli/ войдёт в существующий репо (backend/web) — конфиг переопределит локальный husky этого репо. Тогда лучше переехать на корневой lefthook.yml с per-package задачами.

CI

.github/workflows/ci.yml:

• lint-and-build на каждый push/PR — install → lint → typecheck → smoke-compile.
• release-binaries на тег v* — матрица из 5 платформ (linux/darwin/windows × x64/arm64), сборка через bun build --compile --target=..., аплоад в GitHub Release.

Для активации release-jobов нужен публичный репо + GitHub token с contents: write (softprops/action-gh-release@v2 использует GITHUB_TOKEN по умолчанию).

Стек: Bun + TypeScript + commander + @clack/prompts + kleur. Нет кодогенерации схем — клиент типизирован вручную (минимально, чтобы не блокироваться на drift). Когда appearance стабилизируется — можно добавить openapi-typescript от /openapi.json.

Известные ограничения

• na keys list/create/revoke пока не реализовано: соответствующие endpoint-ы шлюза (/me/keys) требуют session-cookie и недоступны через API-ключ. Управляй ключами через web UI.
• Аплоад больших файлов (POST /me/uploads) пока не обёрнут — для image-to-image задавай URL входа напрямую через -i image=https://... или встраивай локальный файл через @./file.png (data URL).
• Device-flow login — на будущее (требует поддержки на стороне backend).