Referência de comandos

Lista completa dos comandos da CLI. Para ver a ajuda integrada a qualquer momento:

almirant --help
almirant <comando> --help

---

almirant install

Instala uma instância self-hosted do Almirant na máquina atual.

Clona o repositório fonte em --dir (padrão ~/.almirant/stack) e executa o script scripts/install.sh, que constrói as imagens Docker, gera .env.production com segredos aleatórios e inicia o stack.

almirant install [flags]

Flag	Padrão	Descrição
--branch	main	Branch ou tag do git a instalar
--dir	~/.almirant/stack	Diretório onde clonar o stack
--from-dir	—	Usa um clone local já existente (instalação air-gapped, a CLI não toca no git)
--non-interactive	false	Pula os prompts do instalador (usa os padrões)
--public-url	—	URL pública em que o Almirant será servido (sem barra final)
--repo	almirant-ai/almirant	Repositório GitHub a clonar
--with-discord	false	Ativa o profile da bridge do Discord
--with-proxy	false	Ativa o profile do proxy reverso (Caddy)

Comportamento

• Se --dir já contiver um clone anterior, a CLI executa git fetch + pull fast-forward em --branch, em vez de clonar novamente.
• O instalador gera .env.production somente na primeira vez. Se o arquivo já existir, ele será mantido como está (seus segredos permanecem).
• O --public-url é gravado simultaneamente em NEXT_PUBLIC_SITE_URL, BETTER_AUTH_URL, BETTER_AUTH_TRUSTED_ORIGINS e CORS_ORIGIN. Alterar essa URL depois exige reconstruir o frontend (veja Operar o stack).

Exemplos

# Instalacion interactiva, te pregunta la URL publica
almirant install

# Instalacion sin prompts, con URL fijada
almirant install --non-interactive --public-url https://almirant.example.com

# Instalacion desde un tag concreto
almirant install --branch v1.2.3

# Instalacion air-gapped desde un clone existente
almirant install --from-dir /opt/almirant-release --non-interactive

observação

O instalador precisa ser executado na máquina de destino. Não há modo remoto por SSH no install; para isso, use almirant upgrade --host <ssh> em um stack já instalado.

---

almirant login

Abre o navegador para concluir um fluxo OAuth com o backend do Almirant, captura a API key gerada e salva uma conta em ~/.almirant/config.json.

almirant login [flags]

Flag	Padrão	Descrição
--api-url	prompt	URL base da API (sobrescreve ALMIRANT_API_URL e o prompt)
--app-url	derivada de --api-url	URL base do frontend
--name	Almirant CLI	Rótulo com o qual a API key será salva no backend

Cada login cria ou atualiza uma conta local com ID estável e rótulo legível. Você pode repeti-lo para SaaS, staging e várias instâncias self-hosted.

almirant login
almirant login --api-url https://almirant.miempresa.com/api
almirant accounts list

dica

As API keys ficam em ~/.almirant/config.json com permissões 600. Os arquivos de projeto gerados por init e link não contêm bearer tokens.

---

almirant init

Fluxo completo do primeiro uso em um repositório. Detecta o tipo de projeto, permite escolher ou criar uma conta, seleciona ou cria um projeto e grava:

• .mcp.json — configuração MCP sem segredos que executa almirant mcp proxy.
• .claude/skills/ e .agents/skills/ — modelos de skills.

almirant init [flags]

Flag	Padrão	Descrição
--api-url	—	URL da API (somente ao adicionar uma nova conta)
--app-url	—	URL do frontend (somente ao adicionar uma nova conta)
--name	Almirant CLI	Rótulo da API key (somente para nova conta)

Comportamento

• Se você já tiver contas salvas, init permite escolher uma delas.
• Se não tiver nenhuma conta, inicia o fluxo OAuth como almirant login.
• Se .mcp.json já existir, mescla a entrada almirant sem alterar outros servidores MCP.
• A entrada gerada usa type: "stdio", command: "almirant" e args: ["mcp", "proxy", ...].

---

almirant link

Igual ao init, mas sem fluxo OAuth. Exige que você já tenha autenticado pelo menos uma conta com almirant login.

almirant link

Não aceita flags além de --help. Escolhe uma conta e um projeto entre os que você já tem salvos e grava .mcp.json + skills no diretório atual.

Quando usar cada um

• init — primeira vez em uma nova equipe ou se você quiser que a CLI guie todo o processo, incluindo o login.
• link — você já se autenticou antes e quer apenas conectar mais um repositório a um projeto existente.

---

almirant accounts

Gerencia contas pelo atalho principal. Os mesmos subcomandos também existem em almirant config accounts ... por compatibilidade.

almirant accounts list
almirant accounts rename <ref> <label>
almirant accounts add
almirant accounts remove <ref>
almirant accounts set-default <ref>

Subcomando	Descrição
list	Lista marker, índice, rótulo, email, URL da API e estado da API key
add	Alias de almirant login
rename <ref> <label>	Altera o rótulo legível de uma conta
remove <ref>	Remove uma conta local (--yes pula a confirmação)
set-default <ref>	Define a conta ativa por padrão

<ref> pode ser rótulo, ID estável, email único ou índice de base 1.

almirant use [label|id|email|index]

Seleciona a conta ativa. Sem argumento, abre um seletor interativo.

almirant use local-m1pro
almirant current

almirant current imprime rótulo, ID, email, URL da API e prefixo da key, sem expor o token completo.

almirant mcp proxy

Executa o proxy stdio usado pelos agentes MCP.

almirant mcp proxy --project-id <id> [--account <label|id|email|index>]

O proxy lê a conta em ~/.almirant/config.json, encaminha o tráfego para <apiBaseUrl>/mcp?projectId=<id> e anexa o bearer token apenas em memória. Não grave tokens em .mcp.json, .codex/config.toml nem em arquivos de shell.

---

almirant ps

Wrapper de docker compose ps para o arquivo compose de produção.

almirant ps [flags]

Flag	Padrão	Descrição
--dir	~/.almirant/stack	Diretório do stack

---

almirant logs

Wrapper de docker compose logs do stack de produção.

almirant logs [service...] [flags]

Argumentos posicionais — nomes dos serviços aos quais limitar a saída (por exemplo, backend, frontend, db-init).

Flag	Padrão	Descrição
--dir	~/.almirant/stack	Diretório do stack
-f, --follow	false	Acompanha a saída em tempo real (tail -f)
--tail	0 (tudo)	Mostra somente as últimas N linhas por serviço

Exemplos

# Todos los servicios, las ultimas 100 lineas
almirant logs --tail 100

# Solo backend y frontend, en tiempo real
almirant logs -f backend frontend

---

almirant down

Executa docker compose down no stack de produção. Os volumes de dados são preservados por padrão.

almirant down [flags]

Flag	Padrão	Descrição
--dir	~/.almirant/stack	Diretório do stack
--rmi	—	Também remove imagens. Valores: local ou all
--volumes	false	Destrutivo: também remove os volumes (você perde todos os dados)

aviso

--volumes é irreversível. Use-o somente se quiser começar do zero. Para um teste limpo após uma instalação com falha, normalmente você vai querer: almirant down --volumes.

---

almirant upgrade

Atualiza o stack para a versão mais recente do branch indicado.

Modo local (sem --host): executa git fetch + pull em --dir, reconstrói as imagens e reinicia os contêineres.

Modo remoto (com --host): executa scripts/update-remote.sh na máquina via SSH.

almirant upgrade [service...] [flags]

Argumentos posicionais — nomes dos serviços aos quais limitar a reconstrução (por exemplo, frontend backend). Se forem omitidos, reconstrói tudo.

Flag	Padrão	Descrição
--branch	main	Branch a buscar
--dir	~/.almirant/stack	Diretório do stack (modo local)
--host	—	Host SSH para upgrade remoto
--local-repo	—	Caminho para um clone local para evitar baixar o script (modo remoto)
--repo	almirant-ai/almirant	Repositório do script de upgrade (modo remoto)

Exemplos

# Upgrade completo del stack local
almirant upgrade

# Solo reconstruir el frontend (mas rapido si solo cambiaste UI)
almirant upgrade frontend

# Upgrade de un servidor remoto via SSH
almirant upgrade --host [email protected]

---

almirant config

Gerencia a configuração da CLI salva em ~/.almirant/config.json. No dia a dia, prefira os atalhos almirant accounts, almirant use e almirant current; config mantém a árvore completa e os subcomandos avançados.

almirant config [comando]

almirant config show

Imprime todas as contas configuradas sem expor segredos. A API key é mostrada apenas pelo prefixo (por exemplo, alm_k1_…). A chave completa nunca é impressa.

almirant config accounts

Alias completo do gerenciador de contas. Também disponível como almirant accounts ....

Subcomando	Descrição
list	Lista todas as contas configuradas
add	Alias de almirant login — adiciona uma nova conta
rename <ref> <label>	Renomeia o rótulo legível de uma conta
remove <ref>	Remove uma conta da configuração local
set-default <ref>	Define qual é a conta ativa por padrão

almirant config set

Subcomando	Descrição
api-url <url> [--account <ref>]	Altera a URL da API de uma conta (útil se o backend mudou de lugar)

almirant config rotate

Subcomando	Descrição
api-key [--account <ref>]	Gera uma nova API key para a conta selecionada e substitui a anterior. A chave anterior é invalidada no servidor.

almirant config reset

Remove todas as contas e deixa a configuração vazia.

almirant config reset       # te pide confirmacion
almirant config reset -y    # sin prompt, para scripts

---

almirant version

Imprime a versão da CLI e os metadados do build.

almirant version

Útil para reportar issues e decidir se vale a pena atualizar com bun add -g almirant@latest.

---

Variáveis de ambiente

Vários comandos respeitam variáveis de ambiente equivalentes às suas flags. Elas são listadas aqui porque são úteis em CI e scripts.

Variável	Comando afetado	Equivalente à flag
ALMIRANT_API_URL	login, init	--api-url
ALMIRANT_APP_URL	login, init	--app-url
ALMIRANT_NONINTERACTIVE	install (via scripts/install.sh)	--non-interactive
ALMIRANT_PUBLIC_URL	install (via scripts/install.sh)	--public-url
ALMIRANT_WITH_PROXY	install	--with-proxy
ALMIRANT_WITH_DISCORD	install	--with-discord