Referência da CLI

A CLI do Almirant permite autenticar em uma ou mais instâncias, vincular repositórios a projetos e expor o servidor MCP aos seus agentes sem gravar tokens nos arquivos do projeto.

Instalação

npm i -g almirant

Verifique a instalação:

almirant version

Comandos principais

Comando	Descrição
almirant login	Autentica pelo navegador e salva uma conta em ~/.almirant/config.json
almirant accounts list	Lista as contas configuradas sem mostrar segredos
almirant accounts rename <ref> <label>	Atribui um rótulo legível a uma conta
almirant use [ref]	Seleciona a conta ativa; sem argumento, abre um seletor interativo
almirant current	Mostra a conta ativa sem expor a API key
almirant link	Vincula o repositório atual a um projeto usando credenciais armazenadas
almirant init	Configura o Almirant MCP para o projeto atual (fluxo completo)
almirant mcp proxy --project-id <id> [--account <ref>]	Proxy stdio usado por agentes MCP; lê o token da configuração local

Contas

almirant login pode ser executado várias vezes. Cada conta é salva com:

• um id estável, destinado à configuração gerada;
• um label local, destinado a pessoas (local-m1pro, prod-saas, kroko-dev);
• o e-mail, a URL da API e a API key.

almirant accounts list
almirant accounts rename 2 local-m1pro
almirant use local-m1pro
almirant current

Os comandos que aceitam uma conta usam <ref>: rótulo, ID estável, e-mail único ou índice da lista.

Arquivos gerados

A CLI cria e usa os seguintes arquivos:

Arquivo	Localização	Descrição
config.json	~/.almirant/config.json	Contas e API keys locais; permissões 600
.mcp.json	Raiz do repositório	Configuração MCP sem segredos que executa almirant mcp proxy
.claude/skills/	Raiz do repositório	Skills para Claude Code
.agents/skills/	Raiz do repositório	Skills para outros agentes

informação

O arquivo ~/.almirant/config.json é o único local onde a API key fica armazenada e possui permissões 600. Não o compartilhe nem o envie para o repositório.

MCP sem segredos

almirant init e almirant link geram uma entrada stdio semelhante a esta:

{
  "mcpServers": {
    "almirant": {
      "type": "stdio",
      "command": "almirant",
      "args": ["mcp", "proxy", "--project-id", "<project-id>", "--account", "<account-id>"]
    }
  }
}

O repositório fica vinculado a uma conta específica por meio de --account <account-id>, mas não contém bearer tokens. O proxy lê ~/.almirant/config.json em runtime e anexa o token em memória.

Se você usa Codex e prefere .codex/config.toml, use o mesmo padrão:

[mcp_servers.almirant]
command = "almirant"
args = ["mcp", "proxy", "--project-id", "<project-id>", "--account", "<account-id-or-label>"]

Para que o projeto sempre acompanhe a conta ativa selecionada com almirant use, omita o par --account .... É mais flexível, mas menos seguro para repositórios antigos porque eles podem apontar para a instância errada.

Migrar configurações antigas com token

As configurações antigas tinham type: "http", url e um cabeçalho Authorization: Bearer .... Substitua-as executando novamente:

almirant link

ou altere a entrada manualmente para o proxy stdio exibido acima. Se um token real foi enviado ao repositório em algum momento, faça a rotação pelo Almirant ou com:

almirant config rotate api-key --account <ref>