Visão geral da CLI
A CLI do Almirant (almirant) é uma ferramenta única para dois tipos de usuários:
- Equipes no SaaS que querem conectar seu repositório local a um projeto do Almirant e usar agentes de IA pelo IDE.
- Usuários self-hosted que querem instalar, atualizar e operar uma instância própria do Almirant no Docker.
Os dois fluxos compartilham o mesmo binário e o mesmo arquivo de configuração. Muda apenas o conjunto de comandos usado.
O que você pode fazer
| Tarefa | Comando | Guia |
|---|---|---|
| Autenticar em um backend do Almirant | almirant login | Conectar um repositório |
| Conectar o diretório atual a um projeto | almirant init / almirant link | Conectar um repositório |
| Instalar uma instância self-hosted | almirant install | Instalação self-hosted |
| Ver o estado do stack local | almirant ps | Operar o stack |
| Ler logs do stack local | almirant logs | Operar o stack |
| Parar o stack local | almirant down | Operar o stack |
| Atualizar o stack | almirant upgrade | Operar o stack |
| Gerenciar contas (SaaS, self-hosted) | almirant accounts / almirant use | Várias contas |
Instalar a CLI
A CLI é distribuída como um pacote npm (executável standalone escrito em Go):
bun add -g almirant@latest
# ou
npm i -g almirant
Verifique a instalação:
almirant version
Se você só quer conectar um repositório a um projeto SaaS, o guia mais curto é Conectar um repositório. Você não precisa de mais nada.
Modelo mental
Para entender a saída de qualquer comando, lembre-se destes três conceitos:
1. Contas (~/.almirant/config.json)
A CLI armazena uma ou mais contas. Cada conta é composta por:
apiBaseUrl— onde está o backend (por exemplo,https://api.almirant.aipara SaaS ouhttps://miempresa.com/apipara self-hosted).appBaseUrl— onde está o frontend.id— identificador estável da conta, usado pelas configurações geradas.label— alias local legível (local-m1pro,prod-saas,kroko-dev).apiKey— token que a CLI usa para se autenticar no backend.
Comandos como init, link ou config trabalham em uma conta ativa. Você pode alternar entre várias com almirant use <label> ou com o seletor interativo de almirant use.
2. Stack self-hosted (~/.almirant/stack/)
Se você instalar o Almirant no servidor, a CLI clona o código-fonte em ~/.almirant/stack/ e inicia os contêineres com Docker Compose. Todos os comandos ps, logs, down e upgrade usam esse diretório por padrão (alterável com --dir).
O stack local e as contas são independentes: você pode ter um stack self-hosted em execução e, ao mesmo tempo, contas configuradas para o SaaS, sem conflito.
3. Projeto vinculado (.mcp.json + .agents/)
Ao executar almirant init ou almirant link na raiz de um repositório, a CLI grava duas coisas nele:
.mcp.json— configuração MCP sem segredos. Não contém tokens: executaalmirant mcp proxy, que lê a conta de~/.almirant/config.jsone anexa o bearer token em memória..agents/e.claude/skills/— templates de skills para que os agentes saibam como interagir com o Almirant.
Nada disso modifica o banco de dados do Almirant: são apenas metadados locais do repositório.
Para onde ir agora
- Se sua equipe já tem uma conta do Almirant (SaaS ou instância implantada) e você só quer conectar seu repositório: Conectar um repositório.
- Se você quer iniciar o Almirant em um servidor próprio do zero: Instalação self-hosted.
- Se já tem o stack em execução e quer saber como operá-lo no dia a dia: Operar o stack.
- Se precisa consultar um comando específico: Referência de comandos.