Comandos da CLI

Opções globais

Estas opções estão disponíveis em todos os comandos:

Opção	Descrição
--version, -V	Exibe a versão do Archgate
--help, -h	Mostra ajuda para qualquer comando

archgate --version
archgate check --help

---

archgate login

Autentique-se com o GitHub para acessar os plugins de editor do Archgate.

archgate login

Inicia um GitHub Device Flow (OAuth). A CLI exibe um código de uso único e uma URL. Abra a URL no seu navegador, insira o código e autorize o Archgate GitHub OAuth App. Após a autorização, a CLI troca sua identidade do GitHub por um token de plugin do Archgate e armazena ambos em ~/.archgate/credentials.

As credenciais são necessárias para instalar plugins de editor via archgate init --install-plugin. A CLI em si (check, init, etc.) funciona sem login.

Plugin em beta

Os plugins de editor estão atualmente em beta. Cadastre-se em plugins.archgate.dev para obter acesso.

Subcomandos

Subcomando	Descrição
archgate login	Autenticar (pula se já estiver logado)
archgate login status	Mostrar o status atual de autenticação
archgate login logout	Remover credenciais armazenadas
archgate login refresh	Reautenticar e solicitar um novo token

Exemplos

Fazer login pela primeira vez:

archgate login

Authenticating with GitHub...

Open https://github.com/login/device in your browser
and enter the code: ABCD-1234

Waiting for authorization...
GitHub user: yourname
Claiming archgate plugin token...

Authenticated as yourname. Plugin access is now available.
Run `archgate init` to set up a project with the archgate plugin.

Verificar o status do login:

archgate login status

Logged in as yourname (since 2026-02-28)

Fazer logout:

archgate login logout

Reautenticar:

archgate login refresh

---

archgate init

Inicializa a governança do Archgate no projeto atual.

archgate init [options]

Cria o diretório .archgate/ com um ADR de exemplo, arquivo de regras complementar e configuração do linter. Opcionalmente configura a integração com o editor para fluxos de trabalho com agentes de IA e instala o plugin de editor do Archgate.

Opções

Opção	Padrão	Descrição
--editor <editor>	claude	Integração de editor a configurar (claude, cursor, vscode, copilot)
--install-plugin	auto	Instalar o plugin de editor do Archgate (requer archgate login prévio)

Quando --install-plugin é passado, a CLI instala o plugin do Archgate para o editor selecionado. Se a flag for omitida, a CLI faz detecção automática: instala o plugin quando existem credenciais válidas (de um archgate login anterior) e pula caso contrário.

Comportamento de instalação do plugin

Claude Code: Se a CLI claude estiver no seu PATH, o plugin é instalado automaticamente via claude plugin marketplace add e claude plugin install. Se a CLI claude não for encontrada, o comando exibe os comandos de instalação manual.

Cursor: O pacote do plugin é baixado de plugins.archgate.dev e extraído no diretório .cursor/.

Saída

Initialized Archgate governance in /path/to/project
  adrs/          - architecture decision records
  lint/          - linter-specific rules
  .claude/       - Claude Code settings configured

Archgate plugin installed for Claude Code.

Quando --editor cursor é usado, a saída mostra .cursor/ em vez de .claude/.

Estrutura gerada

.archgate/
  adrs/
    ARCH-001-example.md          # Example ADR
    ARCH-001-example.rules.ts    # Example rules file
  lint/
    archgate.config.ts           # Archgate configuration

---

archgate plugin

Gerencia os plugins de editor do Archgate independentemente do archgate init.

archgate plugin <subcomando> [options]

Use archgate plugin para instalar plugins ou obter a URL autenticada do repositório em projetos que já foram inicializados.

Subcomandos

archgate plugin url

Exibe a URL autenticada do repositório de plugins para configuração manual de ferramentas.

archgate plugin url [options]

Opção	Padrão	Descrição
--editor <editor>	claude	Editor alvo (claude, cursor, vscode, copilot)

A URL inclui suas credenciais e pode ser usada para configurar manualmente as ferramentas do editor. Por exemplo, para adicionar o marketplace do Archgate no Claude Code:

claude plugin marketplace add "$(archgate plugin url)"
claude plugin install archgate@archgate

Para o VS Code, a URL aponta para um repositório de plugin separado:

archgate plugin url --editor vscode

archgate plugin install

Instala o plugin do Archgate para o editor especificado em um projeto já inicializado.

archgate plugin install [options]

Opção	Padrão	Descrição
--editor <editor>	claude	Editor alvo (claude, cursor, vscode, copilot)

O comportamento de instalação varia por editor:

• Claude Code: Instala automaticamente via CLI claude se disponível; exibe comandos manuais caso contrário.
• Copilot CLI: Instala automaticamente via CLI copilot se disponível; exibe comandos manuais caso contrário.
• Cursor: Baixa e extrai o pacote do plugin no diretório .cursor/.
• VS Code: Adiciona a URL do marketplace nas configurações de usuário do VS Code.

Exemplos

Obter a URL do plugin para configuração manual:

archgate plugin url

Instalar o plugin para o Claude Code:

archgate plugin install

Instalar o plugin para o Cursor:

archgate plugin install --editor cursor

---

archgate check

Executa todas as verificações automatizadas de conformidade com ADRs no codebase.

archgate check [options]

Carrega cada ADR com rules: true no frontmatter, executa o arquivo .rules.ts complementar e reporta violações com caminhos de arquivo e números de linha.

Opções

Opção	Descrição
--staged	Verificar apenas arquivos no git stage (útil para hooks de pre-commit)
--json	Saída JSON legível por máquina
--ci	Formato de anotação do GitHub Actions
--adr <id>	Verificar apenas regras de um ADR específico
--verbose	Mostrar regras aprovadas e informações de tempo

Códigos de saída

Código	Significado
0	Todas as regras passaram. Nenhuma violação encontrada.
1	Uma ou mais violações detectadas.
2	Erro interno (ex.: ADR ou regra malformada).

Exemplos

Verificar o projeto inteiro:

archgate check

Verificar apenas arquivos no stage antes de commitar:

archgate check --staged

Verificar um único ADR:

archgate check --adr ARCH-001

Obter saída JSON para integração com CI:

archgate check --json

Obter anotações do GitHub Actions:

archgate check --ci

Formato da saída JSON

Quando --json é usado, a saída é um único objeto JSON:

{
  "pass": false,
  "total": 4,
  "passed": 3,
  "failed": 1,
  "warnings": 0,
  "errors": 1,
  "infos": 0,
  "ruleErrors": 0,
  "truncated": false,
  "results": [
    {
      "adrId": "ARCH-001",
      "ruleId": "register-function-export",
      "description": "Command file must export a register*Command function",
      "status": "fail",
      "totalViolations": 1,
      "shownViolations": 1,
      "violations": [
        {
          "message": "Command file must export a register*Command function",
          "file": "src/commands/broken.ts",
          "severity": "error"
        }
      ],
      "durationMs": 12
    }
  ],
  "durationMs": 42
}

---

archgate adr create

Cria um novo ADR interativamente ou via flags.

archgate adr create [options]

Quando executado sem --title e --domain, o comando solicita interativamente o domínio, título e padrões de arquivo opcionais. Quando ambos --title e --domain são fornecidos, ele executa de forma não interativa.

O ID do ADR é gerado automaticamente com o prefixo do domínio e o próximo número de sequência disponível (ex.: ARCH-002, BE-001).

Opções

Opção	Descrição
--title <title>	Título do ADR (pula o prompt interativo)
--domain <domain>	Domínio do ADR (backend, frontend, data, architecture, general)
--files <patterns>	Padrões de arquivo, separados por vírgula
--body <markdown>	Corpo completo do ADR em markdown (pula o template)
--rules	Define rules: true no frontmatter
--json	Saída como JSON

Exemplos

Modo interativo:

archgate adr create

Modo não interativo:

archgate adr create \
  --title "API Response Envelope" \
  --domain backend \
  --files "src/api/**/*.ts" \
  --rules

---

archgate adr list

Lista todos os ADRs do projeto.

archgate adr list [options]

Opções

Opção	Descrição
--json	Saída como JSON
--domain <domain>	Filtrar por domínio

Exemplos

Listar todos os ADRs em formato de tabela:

archgate adr list

ID          Domain        Rules  Title
────────────────────────────────────────────────────────
ARCH-001    architecture  true   Command Structure
ARCH-002    architecture  true   Error Handling
BE-001      backend       true   API Response Envelope

Listar ADRs como JSON:

archgate adr list --json

Filtrar por domínio:

archgate adr list --domain backend

---

archgate adr show

Exibe um ADR específico pelo ID.

archgate adr show <id>

Imprime o conteúdo completo do ADR (frontmatter e corpo) na saída padrão.

Argumentos

Argumento	Descrição
<id>	ID do ADR (ex.: ARCH-001, BE-003)

Exemplo

archgate adr show ARCH-001

---

archgate adr update

Atualiza um ADR existente pelo ID.

archgate adr update --id <id> --body <markdown> [options]

Substitui o corpo do ADR pelo markdown fornecido. Campos do frontmatter (--title, --domain, --files, --rules) são atualizados apenas quando passados explicitamente; caso contrário, os valores existentes são preservados.

Opções

Opção	Obrigatório	Descrição
--id <id>	Sim	ID do ADR a atualizar (ex.: ARCH-001)
--body <markdown>	Sim	Corpo completo do ADR em markdown (substitui o existente)
--title <title>	Não	Novo título do ADR (preserva o existente se omitido)
--domain <domain>	Não	Novo domínio (backend, frontend, data, architecture, general)
--files <patterns>	Não	Novos padrões de arquivo, separados por vírgula (preserva existente se omitido)
--rules	Não	Define rules: true no frontmatter
--json	Não	Saída como JSON

Exemplo

archgate adr update \
  --id ARCH-001 \
  --title "Updated Command Structure" \
  --body "## Context\n\nUpdated context..."

---

archgate upgrade

Atualiza o Archgate para a versão mais recente via npm.

archgate upgrade

Verifica o registro npm para a versão mais recente publicada. Se uma versão mais nova estiver disponível, executa npm install -g archgate@latest para atualizar. Se já estiver atualizado, exibe uma mensagem e encerra.

Exemplo

archgate upgrade

Checking for latest Archgate release...
Upgrading 0.3.0 -> 0.4.0...
Archgate upgraded to 0.4.0 successfully.

---

archgate clean

Remove o diretório de cache da CLI.

archgate clean

Remove ~/.archgate/, que armazena dados em cache como timestamps de verificação de atualização. Seguro para executar a qualquer momento — o diretório é recriado automaticamente quando necessário.

Exemplo

archgate clean

/home/user/.archgate cleaned up