gitflic-cli

gitflic-cli — лёгкий CLI для повседневной работы с GitFlic из терминала, скриптов и AI-агентов: merge-реквесты, обсуждения, задачи, релизы, ветки, теги, коммиты, файлы, вебхуки, окружения, реестр пакетов, CI/CD и администрирование. Все 20 разделов публичного REST API GitFlic обёрнуты в единый бинарник gitflic.

Чем это не является: официальный cli.jar от GitFlic — это серверный инструмент админа (починка LFS/релизов для self-hosted). gitflic-cli — недостающий пользовательский CLI для ежедневной работы.

✨ Почему

• Ноль зависимостей. Чистый Node ESM (≥18) на глобальном fetch. Никакого npm install.
• 100% REST API. Все 20 разделов (~199 эндпоинтов со scope-вариантами). Большинство протестировано вживую. → таблица покрытия
• Дружелюбен к агентам. Каждая команда принимает --format json и пишет стабильный JSON в stdout. Код возврата: 0 при успехе, 1 при HTTP-ошибке. Плюс NDJSON-стриминг (--stream) и авто-пагинация (--all).
• MCP-сервер для AI (Claude Code, Cursor и т.п.) — типизированные тулы поверх всего CLI.
• Безопасное хранение токенов — macOS Keychain / Linux libsecret / chmod 0600 fallback (как у gh/glab). Multi-account + per-project bindings.
• Самодокументирующийся. gitflic help и gitflic <cmd> help показывают все подкоманды и флаги.

📦 Установка

Требуется Node 18+.

# npm (рекомендуется) — ноль транзитивных зависимостей
npm install -g gitflic-cli

# или разово, без установки
npx gitflic-cli help

# SSH-клон + установщик (кладёт CLI в ~/.local/share, symlink в ~/.local/bin)
git clone git@gitflic.ru:tikhon/gitflic-cli.git ~/tools/gitflic-cli
cd ~/tools/gitflic-cli && bash install.sh

# Windows / PowerShell
powershell -ExecutionPolicy Bypass -File install.ps1

# Кастомный путь / без symlink / dry-run
bash install.sh --prefix ~/my-tools
bash install.sh --no-symlink
bash install.sh --dry-run

→ Подробно: Установка

🔐 Аутентификация

gitflic auth login --token xxxx-xxxx-xxxx   # валидирует через /user/me, кладёт в Keychain
gitflic auth status                         # backend + identity

Поддерживаются несколько аккаунтов (auth login --as work, auth switch) и привязка проектов к аккаунтам (auth bind owner/alias work). Альтернатива — GITFLIC_TOKEN в окружении.

→ Подробно: Аутентификация · Multi-account · Безопасность

🚀 Использование

gitflic mr list --project tikhon/gitflic-cli            # список merge-реквестов
gitflic mr create --title "Fix login" --to main         # авто: текущая ветка → default
gitflic mr diff 42                                       # дифф (с декодом HTML-entities)
gitflic mr merge 42 --message "Squash: fix login"

gitflic issue create --title "Bug" --description "..."
gitflic release create --title v1.0.0 --tag v1.0.0
gitflic release upload <uuid> ./build.zip               # ассеты релиза

gitflic branch protection create --scope team --team acme \
  --branch-template "main" --allowed-to-push NO_ONE --allowed-to-merge DEVELOPER

gitflic registry package upload --fmt maven --project me/app \
  ./app.jar com.example app 1.0.0 app.jar               # реестр пакетов

gitflic user me --format json | jq .username           # машинный вывод

gitflic help — полный список, gitflic <cmd> help — справка по модулю.

🧩 Команды

→ Полный справочник с примерами: cli-gitflic.ru/commands

✅ Покрытие API

100% — все 20 разделов публичного REST GitFlic (~199 эндпоинтов; со scope-вариантами project/company/team/instance — больше). Часть admin/SAML/Enterprise — code-only (нужны права/редакция инстанса).

→ Подробная таблица по разделам: cli-gitflic.ru/api-coverage

🤖 Для AI-агентов

Каждая команда поддерживает --format json — агент или shell-пайплайн получает стабильный JSON.

# Открытые MR в проекте
gitflic mr list --project tikhon/wave --format json \
  | jq '[._embedded.mergeRequestModelList[] | select(.status.id == "OPENED")] | length'

Есть MCP-сервер (Model Context Protocol) с типизированными тулами поверх CLI — подключается к Claude Code, Cursor и др. через npx, без установки:

claude mcp add gitflic --env GITFLIC_TOKEN=xxxx -- npx -y gitflic-cli-mcp

Набор из 77 тулзов можно сузить, чтобы не «съедать» контекст модели: GITFLIC_MCP_GROUPS=mr,issue (по группам), GITFLIC_MCP_READONLY=1 (только чтение) и др.

→ MCP-сервер. Для ИИ также опубликованы /llms.txt и /llms-full.txt.

🏗️ Архитектура

gitflic-cli/
├── bin/gitflic              # bash-шим → node lib/gitflic.mjs
├── lib/
│   ├── gitflic.mjs          # диспетчер команд
│   ├── http.mjs             # fetch + retry + httpText/httpDownload/httpUploadFile
│   ├── secret.mjs           # Keychain / libsecret / chmod 0600
│   ├── paginate.mjs         # --all авто-пагинация + NDJSON streaming
│   ├── format.mjs           # вывод, цвета, htmlUnescape
│   └── cmd/                 # модули команд (mr, branch, release, registry, …)
├── mcp-server/              # Model Context Protocol сервер
├── docs/                    # документация (VitePress → cli-gitflic.ru)
└── install.sh / install.ps1 # установщики

🛠️ Разработка

npm test            # 256 unit-тестов (vitest)
npm run build       # lint + тесты + portable tar.gz → dist/
npm run docs:dev    # локальный VitePress dev-server
npm run docs:publish # собрать и задеплоить доку

→ Подробно: Локальная разработка

📄 Лицензия

MIT.