@arzstack/hub

CLI + servidor MCP do ArzStack Hub: instala itens do catálogo (skills, MCPs…) com um comando (type-aware, destino projeto/global) e expõe o catálogo ao seu agente via MCP — tudo com o mesmo Token de CLI.

Uso rápido

# 1) autentique uma vez (gere o token no Hub: Perfil → Tokens de CLI)
npx @arzstack/hub login          # pergunta o hub + token

# 2a) modo interativo — navegue o catálogo e instale (sem precisar do id)
npx @arzstack/hub install        # (ou: npx @arzstack/hub browse)

# 2b) instale um item direto (o id está na página do item no Hub)
npx @arzstack/hub install <id> --global     # ou --project

Prefere instalar global? npm i -g @arzstack/hub e use arzstack-hub ….

Modo interativo (navegar o catálogo)

Rode install sem argumento (ou browse) e o CLI guia você pelo catálogo da sua org, usando o token salvo:

Instalar — escolha um tipo:
  a. Skill (3)
  b. MCP Server (1)
  c. Knowledge (2)
      → escolhe a letra
  1. Resumo de chamados (v1.0.0)
  2. …                              ([m] mais · [v] voltar)
      → escolhe o número
Instalar onde? [g] global · [p] projeto
      → instala

Conta com contagem por tipo, lista paginada e a escolha de projeto/global na hora — tudo sem você ter que copiar id nem comando da web.

O que ele faz, por tipo

| tipo | ação | destino | |---|---|---| | skill | git clone da skill | --global: ~/.agents/skills/<slug> · --project: .agents/skills/<slug> | | mcp_server | roda o comando de configuração (ex.: claude mcp add …) | — | | outros | mostra repositório / próximos passos | — |

Sempre confirma antes de executar (use --yes pra pular).

Agente (onde as skills caem)

Cada agente lê skills de uma pasta diferente: Claude Code → .claude/skills; Codex/Gemini/outros → .agents/skills. O login pergunta qual você usa (salvo no config local); troque com arzstack-hub agent ou sobrescreva por comando com --agent claude / --agent agents. ⚠️ Usa Claude Code? Escolha claude — senão a skill cai em .agents/skills, que o Claude Code não lê.

Autenticação

arzstack-hub login salva hub + token (+ agent) em ~/.config/arzstack/config.json. Alternativas: variáveis ARZSTACK_HUB / ARZSTACK_TOKEN (bom pra CI), ou as flags --hub / --token. O token é pessoal, revogável e escopado à sua org (gere/gerencie no Hub em Perfil → Tokens de CLI).

Manter atualizado

O CLI registra o que você instala (em ~/.config/arzstack/installed.json), então dá pra ver e atualizar depois:

npx @arzstack/hub list        # o que está instalado (item, versão, caminho)
npx @arzstack/hub outdated    # itens com versão nova no catálogo
npx @arzstack/hub update      # git pull --ff-only nos desatualizados (ou: update <id>)

"Desatualizado" = a versão declarada no catálogo é maior que a instalada. Itens não-git (ex.: MCP) não atualizam sozinhos — o CLI avisa pra reinstalar.

Setup de time reproduzível (add + sync)

Um .arzstack.json commitado no repo declara o conjunto de itens do projeto. O time monta com add; quem clona o repo roda sync e fica idêntico — um comando, sem copiar nada:

npx @arzstack/hub add <id>     # instala no projeto + grava no .arzstack.json (commitar)
npx @arzstack/hub remove <id>  # tira do manifesto + apaga a instalação
# dev novo, depois de clonar:
npx @arzstack/hub login        # token dele
npx @arzstack/hub sync         # instala tudo do .arzstack.json (idempotente, resumível)
npx @arzstack/hub sync --update  # também dá git pull nos presentes
npx @arzstack/hub sync --prune   # remove o que saiu do manifesto

O .arzstack.json nasce no primeiro add. sync/remove acham ele subindo na árvore (funcionam de qualquer subpasta). sync = set declarado do projeto (no git). update = atualizar o que você já instalou na sua máquina. São coisas diferentes e complementares.

Servidor MCP (usar no agente)

O mesmo pacote sobe um servidor MCP (stdio) que dá ao seu agente as ferramentas search_catalog, catalog_counts e get_item — ele descobre e instala itens do catálogo sozinho. Usa o mesmo login do CLI.

Se você já rodou arzstack-hub login, a config do agente fica sem URL e sem token (o MCP lê do ~/.config/arzstack/config.json):

# Claude Code
claude mcp add arzstack-hub -- npx -y @arzstack/hub mcp

{ "mcpServers": { "arzstack-hub": { "command": "npx", "args": ["-y", "@arzstack/hub", "mcp"] } } }

Só se não tiver feito login (máquina nova, CI), passe hub + token por env:

claude mcp add arzstack-hub --env ARZSTACK_HUB=<hub> --env ARZSTACK_TOKEN=arz_… -- npx -y @arzstack/hub mcp

Comandos e flags

arzstack-hub login    [--hub <url>] [--token <pat>] [--agent <claude|agents>]
arzstack-hub agent    [<claude|agents>]                      # onde as skills são instaladas
arzstack-hub browse   [--global | --project]                 # navegar e instalar
arzstack-hub install  [<id|token>] [--global | --project] [--dir <path>] [--yes]
                      # sem <id|token>, "install" abre o modo interativo (= browse)
arzstack-hub list                                            # o que está instalado
arzstack-hub outdated                                        # itens com versão nova
arzstack-hub update   [<id>]                                 # atualiza os desatualizados
arzstack-hub add      <id>                                   # instala no projeto + .arzstack.json
arzstack-hub remove   <id>                                   # tira do .arzstack.json + apaga
arzstack-hub sync     [--update] [--prune]                   # instala o set do .arzstack.json
arzstack-hub mcp      [--hub <url>] [--token <pat>]          # servidor MCP pro agente

Mantenedores: publicado via GitHub Actions (Trusted Publishing/OIDC) a cada bump de version. Fonte e contrato: repositório do ArzStack Hub (docs/specs/install-experience.md, cli-auth.md, mcp-server.md).