GitFlic

gitflic-cli

Cliente completo de console para a REST API GitFlic. 100% de cobertura · zero dependências externas · servidor MCP para agentes de IA.

📖 Documentação · 🚀 Início rápido · 🧩 Comandos · 📦 Baixar · 🤖 MCP para IA

---

gitflic-cli — um CLI leve para o trabalho diário com o GitFlic a partir do terminal, scripts e agentes de IA: merge requests, discussões, tarefas, releases, branches, tags, commits, arquivos, webhooks, ambientes, registro de pacotes, CI/CD e administração. Todas as 20 seções da REST API pública do GitFlic estão empacotadas em um único binário gitflic.

O que isto não é: o cli.jar oficial do GitFlic é uma ferramenta de servidor para administradores (correção de LFS/releases para self-hosted). gitflic-cli é o CLI de usuário que faltava para o trabalho diário.

✨ Por quê

• Zero dependências. Node ESM puro (≥18) no fetch global. Nada de npm install.
• 100% da REST API. Todas as 20 seções (~199 endpoints com variantes de escopo). A maioria testada ao vivo. → tabela de cobertura
• Amigável para agentes. Cada comando aceita --format json e escreve JSON estável no stdout. Código de retorno: 0 em caso de sucesso, 1 em caso de erro HTTP. Além de streaming NDJSON (--stream) e paginação automática (--all).
• Servidor MCP para IA (Claude Code, Cursor etc.) — ferramentas tipadas sobre todo o CLI.
• Armazenamento seguro de tokens — macOS Keychain / Linux libsecret / fallback chmod 0600 (como no gh / glab). Multi-contas + vínculos por projeto.
• Autodocumentável. gitflic help e gitflic <cmd> help mostram todos os subcomandos e flags.

📦 Instalação

Requer Node 18+.

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

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

A partir do código-fonte (git clone + install.sh) e outras 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

Arquivos tar.gz prontos — na página de downloads.

→ Detalhes: Instalação

🔐 Autenticação

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

Suporte a várias contas (auth login --as work, auth switch) e vínculo de projetos a contas (auth bind owner/alias work). Alternativa — GITFLIC_TOKEN no ambiente.

→ Detalhes: Autenticação · Multi-contas · Segurança

🚀 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 — ajuda por módulo.

🧩 Comandos

Módulo	O que faz
auth	login / logout / status / switch / list / bind / unbind — multi-contas, por projeto
mr	list / view / diff / create / edit / approve / merge / close / cancel / by-commit / comment / discuss + regras de aprovação e configurações de MR (team/company)
branch	list / get / default / create / delete / compare / compare-file / commits + proteção de branch (project/team/company)
tag	list / get / create + proteção de tags (team/company)
release	list / get / latest / create / edit / delete + upload / download / delete-file
issue	CRUD + comentários + relações + arquivos (link/unlink) + attach
commit	list / get / files / diff / for-file / commit-diff / tag-diff / cherry-pick
blob	get (raw) / download / recursivo / file-size
project	CRUD + search/my/shared + members/teams + fork/mirror/import + archive + anexos + change-setting + deploy-token + run-script
user	me / get / projects / followers / following
settings	ssh / oauth / access-token / transport-token / alterar email·username·password
team · company	list / my / shared / get / create + members + import (+ transferência de team)
environment	proteção de ambiente (team/company)
webhook	list / get / create / edit / delete
registry	package (CRUD + upload/download para maven/npm/pypi/nuget/cargo/conda/… em 3 escopos) · repo (Enterprise)
cicd	pipeline + ciclo de vida de jobs, artefatos, variáveis, pipeline-lifetime
runner	project / company / instance: list / get / jobs / edit / shutdown / delete
admin · saml	endpoints de administração da instância (exigem privilégios de administrador)

→ Referência completa com exemplos: cli-gitflic.ru/commands

✅ Cobertura da API

100% — todas as 20 seções da REST pública do GitFlic (~199 endpoints; com variantes de escopo project/company/team/instance — mais). Parte de admin/SAML/Enterprise — apenas código (exige privilégios/edição da instância).

→ Tabela detalhada por seção: cli-gitflic.ru/api-coverage

🤖 Para agentes de IA

Cada comando suporta --format json — o agente ou pipeline de shell recebe JSON estável.

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

Há um servidor MCP (Model Context Protocol) com ferramentas tipadas sobre o CLI — conecta-se ao Claude Code, Cursor etc. via npx, sem instalação:

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

O conjunto de 77 ferramentas pode ser reduzido para não "consumir" o contexto do modelo: GITFLIC_MCP_GROUPS=mr,issue (por grupos), GITFLIC_MCP_READONLY=1 (somente leitura) e outros.

→ Servidor MCP. Para IA também foram publicados /llms.txt e /llms-full.txt.

🏗️ Arquitetura

Estrutura do projeto

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 e handle(ctx, sub, args, flags). O dispatcher cuida da resolução do token, resolução do projeto (--project ou detecção automática via git) e geração do help.

🛠️ Desenvolvimento

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