VFLIN
ВойтиСкачать

docs · docs/20-control-plane/CLI_DESIGN.md · перевод от 2026-09-12 · с английской ревизии abe41609bd80

CLI

vflin — одна команда на каждый метод API

Назначение: определить полноценный CLI, который является тонким клиентом Local API один к одному (ADR-0003). CLI существует одинаково для людей, CI, скриптов автоматизации и ИИ-агентов (Claude Code).

Принципы

  • Никакой бизнес-логики. Каждая команда отображается в один вызов API (или в короткую их композицию).
  • Пригоден для скриптов по умолчанию: у каждой команды есть --json для машинного вывода и стабильные коды возврата. Красивый человеческий вывод — только для TTY.
  • Те же глаголы, что у API: vflin <domain> <action> повторяет domain.action.
  • Безопасен по умолчанию: опасные действия требуют --mode danger (или power) И подтверждения, если только не передан --yes в неинтерактивном окружении.

Форма

vflin profile create --name "x" --fingerprint preset:win11-chrome --proxy <id>
vflin profile start <id> [--headless] [--json]
vflin profile stop <id> [--sync]
vflin profile ls [--group y] [--json]
vflin proxy test <id> --json
vflin fingerprint validate -f config.json
vflin automation run --script <id> --group y --var k=v
vflin automation status <runId> --watch
vflin sync push <id> | pull <id> | status <id>
vflin core ls | core select <provider> --version 148.9 | core diagnose
vflin log tail --filter automation
vflin policy set danger        # session-scoped, audited

Вывод и коды возврата

  • 0 успех · 1 общая ошибка · 2 ошибка использования · 3 запрещено политикой · 4 конфликт или заблокировано · 5 не удалось запустить ядро. (Повторяют коды ошибок API.)
  • --json печатает конверт API { ok, data, error } дословно → агенту тривиально его разобрать.

Модель подключения

  • CLI говорит с работающим Application Core через сокет Local API.
  • vflin daemon status|start|stop управляет ядром, если оно ещё не поднято (интерфейс тоже его запускает).

Почему он полноценный с первого дня

  • Критерий выхода из Phase-1 — команда CLI, открывающая настоящий браузер через API.
  • Делает весь продукт тестируемым без окна в CI ещё до того, как появился интерфейс.
  • Становится основой, к которой обращаются или которую повторяют MCP-сервер и навыки Claude Code.

Не цели

  • CLI не читает папки профилей, хранилище или cookies напрямую. Никогда.
  • Никакого альтернативного «быстрого пути» в обход API.

Сессии (Feature c — ADR-0034)

Привязать сохранённую сессию сервиса, чтобы профиль открывался уже вошедшим. Полное руководство оператора: SESSIONS_MODULE.md (internal: docs/20-control-plane/SESSIONS_MODULE.md).

vflin session recipes                              # supported services (green; always prints JSON)
vflin profile session list <id>                    # always prints JSON
vflin profile session get <id> <service>
vflin --mode danger profile session set <id> \
      --service <name> --session-mode <inject|login|companion> \
      --secrets-file <path.json> [--label <l>]
vflin --mode danger profile session clear <id> <service>

Две правила, ради которых эта поверхность и существует:

  • Секреты приходят из ФАЙЛА, никогда из argv. --secrets-file принимает JSON-объект {"field":"value"}, так что токен сессии не попадёт ни в историю оболочки, ни в чужой вывод ps.
  • --mode и --session-mode — разные флаги. --mode — это глобальный режим политики (normal|power|danger), он снимается до диспетчеризации; --session-mode — режим рецепта. Изначально они делили имя --mode, из-за чего задокументированный вызов был буквально невыполним: глобальный валидатор отвергал inject раньше, чем команда его видела (сверка 2026-07-19).