Trabajar con varias cuentas

El CLI soporta N cuentas a la vez. Casos tipicos:

• Cuenta personal en el SaaS + cuenta de empresa en otra organizacion.
• Cuenta en el SaaS para clientes + instancia self-hosted para desarrollo interno.
• Varias instancias self-hosted (produccion, staging, maquina local).

Todas viven en ~/.almirant/config.json.

Modelo mental

Cada cuenta tiene cuatro piezas importantes:

Campo	Para que sirve
id	Identificador estable. Es lo que almirant link escribe en .mcp.json.
label	Nombre local para humanos, como prod-saas o local-m1pro.
apiBaseUrl	Backend contra el que habla el CLI.
apiKey	Token secreto; nunca se imprime completo.

El email no es suficiente como identificador porque el mismo usuario puede existir en varias instancias.

Ver las cuentas configuradas

almirant accounts list
# o, por compatibilidad:
almirant config accounts list

Salida tipica:

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

información

La API key completa nunca se imprime. Solo veras un prefijo o un indicador de estado.

Añadir una cuenta nueva

# SaaS
almirant login

# Backend concreto
almirant login --api-url https://almirant.miempresa.com/api

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

Renombrar cuentas con labels utiles

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

Los labels son locales. Describen la instancia o el proposito, no tienen que coincidir con el email ni con la URL.

Cambiar la cuenta activa

# Selector interactivo
almirant use

# Directo por label, ID, email unico o indice
almirant use local-m1pro
almirant use 2

# Ver la activa
almirant current

La cuenta activa es la que usan los comandos cuando no pasas una cuenta explicita.

Cuenta activa vs cuenta fijada en un repo

Hay dos modos validos:

1. Cuenta fijada — modo por defecto de almirant init / almirant link. El .mcp.json incluye --account <account-id>, asi que el repo siempre habla con la misma instancia aunque mas tarde ejecutes almirant use en otro contexto.
2. Cuenta activa — modo avanzado. Si quitas --account de los argumentos del proxy, el repo sigue la cuenta activa seleccionada con almirant use.

Preferimos el modo fijado: evita que un repo antiguo guarde memoria, tareas o comentarios en la instancia equivocada.

MCP sin secretos

El .mcp.json generado no contiene API keys:

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

almirant mcp proxy lee la cuenta de ~/.almirant/config.json y adjunta el bearer token en memoria.

Codex .codex/config.toml

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

No guardes tokens en .codex/config.toml ni en .zshrc / .bashrc. Si necesitas cambiar de instancia, cambia la activa con almirant use o actualiza el --account del proyecto.

Eliminar una cuenta

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

Esto borra la cuenta del config local. Si quieres invalidar tambien el token en el backend, rota o revoca la API key desde Almirant.

Rotar la API key de una cuenta

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

Genera una clave nueva, sustituye la anterior en el config local e invalida la anterior en el servidor. Como los repos usan el proxy y no guardan tokens, normalmente no tienes que reescribir .mcp.json tras rotar.

Cambiar la URL del API de una cuenta

Util si moviste tu instancia self-hosted a otro dominio:

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

Resetear todo

Para empezar de cero (borra todas las cuentas locales):

almirant config reset
almirant config reset -y