CLI Reference

El CLI de Almirant permite autenticarte contra una o varias instancias, vincular repositorios a proyectos y exponer el servidor MCP a tus agentes sin escribir tokens en archivos del proyecto.

Instalacion

npm i -g almirant

Verifica la instalacion:

almirant version

Comandos principales

Comando	Descripcion
almirant login	Autentica via navegador y guarda una cuenta en ~/.almirant/config.json
almirant accounts list	Lista las cuentas configuradas sin mostrar secretos
almirant accounts rename <ref> <label>	Asigna una etiqueta humana a una cuenta
almirant use [ref]	Selecciona la cuenta activa; sin argumento abre un selector interactivo
almirant current	Muestra la cuenta activa sin exponer la API key
almirant link	Vincula el repositorio actual a un proyecto usando credenciales almacenadas
almirant init	Configura Almirant MCP para el proyecto actual (flujo completo)
almirant mcp proxy --project-id <id> [--account <ref>]	Proxy stdio usado por agentes MCP; lee el token desde el config local

Cuentas

almirant login puede ejecutarse varias veces. Cada cuenta queda guardada con:

• un id estable, pensado para configuracion generada;
• un label local, pensado para humanos (local-m1pro, prod-saas, kroko-dev);
• el email, la URL del API y la API key.

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

Los comandos que aceptan una cuenta usan <ref>: etiqueta, ID estable, email unico o indice de la lista.

Archivos generados

El CLI crea y utiliza los siguientes archivos:

Archivo	Ubicacion	Descripcion
config.json	~/.almirant/config.json	Cuentas y API keys locales; permisos 600
.mcp.json	Raiz del repositorio	Configuracion MCP secretless que ejecuta almirant mcp proxy
.claude/skills/	Raiz del repositorio	Skills para Claude Code
.agents/skills/	Raiz del repositorio	Skills para otros agentes

info

El archivo ~/.almirant/config.json es el unico sitio local donde vive la API key y tiene permisos 600. No lo compartas ni lo subas al repositorio.

MCP sin secretos

almirant init y almirant link generan una entrada stdio parecida a esta:

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

El repo queda fijado a una cuenta concreta mediante --account <account-id>, pero no contiene bearer tokens. El proxy lee ~/.almirant/config.json en runtime y adjunta el token en memoria.

Si usas Codex y prefieres .codex/config.toml, usa el mismo patron:

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

Para que el proyecto siga siempre la cuenta activa seleccionada con almirant use, omite el par --account .... Es mas flexible, pero menos seguro para repos antiguos porque podrian apuntar a la instancia equivocada.

Migrar configuraciones antiguas con token

Las configuraciones antiguas tenian type: "http", url y un header Authorization: Bearer .... Sustituyelas reejecutando:

almirant link

o cambia la entrada manualmente al proxy stdio mostrado arriba. Si un token real se subio alguna vez al repo, rotalo desde Almirant o con:

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