GitFlic

gitflic-cli

Cliente de consola completo para la API REST de GitFlic. 100% de cobertura · cero dependencias externas · servidor MCP para agentes de IA.

📖 Documentación · 🚀 Inicio rápido · 🧩 Comandos · 📦 Descargar · 🤖 MCP para IA

---

gitflic-cli — un CLI ligero para el trabajo diario con GitFlic desde la terminal, scripts y agentes de IA: merge-requests, discusiones, tareas, releases, ramas, etiquetas, commits, archivos, webhooks, entornos, registro de paquetes, CI/CD y administración. Las 20 secciones de la API REST pública de GitFlic están envueltas en un único binario gitflic.

Lo que no es: el cli.jar oficial de GitFlic es una herramienta de servidor para administradores (reparación de LFS/releases para self-hosted). gitflic-cli es el CLI de usuario que faltaba para el trabajo diario.

✨ Por qué

• Cero dependencias. Node ESM puro (≥18) sobre el fetch global. Nada de npm install.
• 100% API REST. Las 20 secciones (~199 endpoints con variantes de scope). La mayoría probado en vivo. → tabla de cobertura
• Amigable con agentes. Cada comando acepta --format json y escribe JSON estable en stdout. Código de retorno: 0 en éxito, 1 en error HTTP. Además, streaming NDJSON (--stream) y auto-paginación (--all).
• Servidor MCP para IA (Claude Code, Cursor, etc.) — herramientas tipadas sobre todo el CLI.
• Almacenamiento seguro de tokens — macOS Keychain / Linux libsecret / fallback chmod 0600 (como en gh / glab). Multi-cuenta + vinculaciones por proyecto.
• Autodocumentado. gitflic help y gitflic <cmd> help muestran todos los subcomandos y flags.

📦 Instalación

Requiere Node 18+.

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

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

Desde el código fuente (git clone + install.sh) y otras alternativas

# 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

Tar.gz listos — en la página de descargas.

→ Detalles: Instalación

🔐 Autenticación

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

Se admiten varias cuentas (auth login --as work, auth switch) y vinculación de proyectos a cuentas (auth bind owner/alias work). Alternativa: GITFLIC_TOKEN en el entorno.

→ Detalles: Autenticación · Multi-cuenta · Seguridad

🚀 Uso

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 — lista completa, gitflic <cmd> help — ayuda por módulo.

🧩 Comandos

Módulo	Qué hace
auth	login / logout / status / switch / list / bind / unbind — multi-cuenta, por proyecto
mr	list / view / diff / create / edit / approve / merge / close / cancel / by-commit / comment / discuss + reglas de aprobación y ajustes de MR (team/company)
branch	list / get / default / create / delete / compare / compare-file / commits + protección de ramas (project/team/company)
tag	list / get / create + protección de etiquetas (team/company)
release	list / get / latest / create / edit / delete + upload / download / delete-file
issue	CRUD + comentarios + relaciones + archivos (link/unlink) + attach
commit	list / get / files / diff / for-file / commit-diff / tag-diff / cherry-pick
blob	get (raw) / download / recursive / file-size
project	CRUD + search/my/shared + members/teams + fork/mirror/import + archive + attachments + change-setting + deploy-token + run-script
user	me / get / projects / followers / following
settings	ssh / oauth / access-token / transport-token / cambio de email·username·password
team · company	list / my / shared / get / create + members + import (+ transferencia de equipo)
environment	protección de entornos (team/company)
webhook	list / get / create / edit / delete
registry	package (CRUD + upload/download para maven/npm/pypi/nuget/cargo/conda/… en 3 scopes) · repo (Enterprise)
cicd	pipeline + ciclo de vida de jobs, artifacts, variables, pipeline-lifetime
runner	project / company / instance: list / get / jobs / edit / shutdown / delete
admin · saml	endpoints de administración de instancia (requieren permisos de administrador)

→ Referencia completa con ejemplos: cli-gitflic.ru/commands

✅ Cobertura de API

100% — las 20 secciones de la REST pública de GitFlic (~199 endpoints; con variantes de scope project/company/team/instance — más). Parte de admin/SAML/Enterprise — solo código (requiere permisos/edición de instancia).

→ Tabla detallada por secciones: cli-gitflic.ru/api-coverage

🤖 Para agentes de IA

Cada comando admite --format json — el agente o pipeline de shell recibe JSON estable.

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

Hay un servidor MCP (Model Context Protocol) con herramientas tipadas sobre el CLI — se conecta a Claude Code, Cursor, etc. mediante npx, sin instalación:

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

El conjunto de 77 herramientas se puede reducir para no «consumir» contexto del modelo: GITFLIC_MCP_GROUPS=mr,issue (por grupos), GITFLIC_MCP_READONLY=1 (solo lectura), etc.

→ Servidor MCP. Para IA también se publican /llms.txt y /llms-full.txt.

🏗️ Arquitectura

Estructura del proyecto

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 # установщики

Cada módulo exporta usage y handle(ctx, sub, args, flags). El despachador se encarga de la resolución del token, la resolución del proyecto (--project o auto-detección desde git) y la generación de help.

🛠️ Desarrollo

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