Trabalhar com várias contas

A CLI aceita N contas ao mesmo tempo. Casos típicos:

• Conta pessoal no SaaS + conta corporativa em outra organização.
• Conta no SaaS para clientes + instância self-hosted para desenvolvimento interno.
• Várias instâncias self-hosted (produção, staging, máquina local).

Todas ficam em ~/.almirant/config.json.

Modelo mental

Cada conta tem quatro partes importantes:

Campo	Para que serve
id	Identificador estável. É o que almirant link grava em .mcp.json.
label	Nome local legível, como prod-saas ou local-m1pro.
apiBaseUrl	Backend com o qual a CLI se comunica.
apiKey	Token secreto; nunca é exibido por completo.

O e-mail não basta como identificador porque o mesmo usuário pode existir em várias instâncias.

Ver as contas configuradas

almirant accounts list
# ou, por compatibilidade:
almirant config accounts list

Saída típica:

[*]  1  local-m1pro       [email protected]                  https://macbook-m1-pro.tailnet.ts.net/api  alm_***
[ ]  2  prod-saas         [email protected]                  https://api.almirant.ai                    alm_***

informação

A API key completa nunca é exibida. Você verá apenas um prefixo ou um indicador de estado.

Adicionar uma nova conta

# SaaS
almirant login

# Backend específico
almirant login --api-url https://almirant.miempresa.com/api

# Alias equivalente
almirant accounts add --api-url https://almirant.miempresa.com/api

Renomear contas com rótulos úteis

almirant accounts rename 1 prod-saas
almirant accounts rename 2 local-m1pro
almirant accounts rename prod-saas clientes

Os rótulos são locais. Eles descrevem a instância ou a finalidade, não precisam corresponder ao e-mail nem à URL.

Alterar a conta ativa

# Seletor interativo
almirant use

# Direto por rótulo, ID, e-mail único ou índice
almirant use local-m1pro
almirant use 2

# Ver a ativa
almirant current

A conta ativa é usada pelos comandos quando você não informa uma conta explicitamente.

Conta ativa versus conta fixada em um repositório

Há dois modos válidos:

1. Conta fixada — modo padrão de almirant init / almirant link. O .mcp.json inclui --account <account-id>, portanto o repositório sempre se comunica com a mesma instância mesmo que você execute almirant use mais tarde em outro contexto.
2. Conta ativa — modo avançado. Se remover --account dos argumentos do proxy, o repositório acompanhará a conta ativa selecionada com almirant use.

É preferível o modo fixado: ele evita que um repositório antigo armazene memória, tarefas ou comentários na instância errada.

MCP sem segredos

O .mcp.json gerado não contém API keys:

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

almirant mcp proxy lê a conta de ~/.almirant/config.json e anexa o bearer token em memória.

Codex .codex/config.toml

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

Não armazene tokens em .codex/config.toml nem em .zshrc / .bashrc. Se precisar trocar de instância, altere a ativa com almirant use ou atualize o --account do projeto.

Remover uma conta

almirant accounts remove <ref>
almirant accounts remove <ref> --yes

Isso remove a conta da configuração local. Se também quiser invalidar o token no backend, faça a rotação ou revogue a API key pelo Almirant.

Fazer a rotação da API key de uma conta

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

Gera uma nova chave, substitui a anterior na configuração local e invalida a anterior no servidor. Como os repositórios usam o proxy e não armazenam tokens, normalmente não é necessário regravar .mcp.json após a rotação.

Alterar a URL da API de uma conta

Útil se você moveu sua instância self-hosted para outro domínio:

almirant config set api-url https://nueva-url.example.com/api --account local-m1pro

Redefinir tudo

Para recomeçar do zero (remove todas as contas locais):

almirant config reset
almirant config reset -y