Vision general del CLI
El CLI de Almirant (almirant) es una herramienta unica para dos tipos de usuarios:
- Equipos en SaaS que quieren conectar su repositorio local a un proyecto de Almirant y usar agentes de IA desde su IDE.
- Self-hosters que quieren instalar, actualizar y operar una instancia propia de Almirant sobre Docker.
Ambos flujos comparten el mismo binario y el mismo archivo de configuracion. Solo cambia el conjunto de comandos que usas.
Que puedes hacer
| Tarea | Comando | Guia |
|---|---|---|
| Autenticarte contra un backend de Almirant | almirant login | Conectar un repositorio |
| Conectar el directorio actual a un proyecto | almirant init / almirant link | Conectar un repositorio |
| Instalar una instancia self-hosted | almirant install | Instalacion self-hosted |
| Ver el estado del stack local | almirant ps | Operar el stack |
| Leer logs del stack local | almirant logs | Operar el stack |
| Parar el stack local | almirant down | Operar el stack |
| Actualizar el stack | almirant upgrade | Operar el stack |
| Gestionar cuentas (SaaS, self-hosted) | almirant accounts / almirant use | Multiples cuentas |
Instalar el CLI
El CLI se distribuye como paquete npm (ejecutable standalone escrito en Go):
bun add -g almirant@latest
# o
npm i -g almirant
Verifica la instalacion:
almirant version
Si solo quieres conectar un repositorio a un proyecto SaaS, la guia mas corta es Conectar un repositorio. No necesitas nada mas.
Modelo mental
Para entender la salida de cualquier comando, recuerda estos tres conceptos:
1. Cuentas (~/.almirant/config.json)
El CLI guarda una o varias cuentas. Cada cuenta es una tripleta:
apiBaseUrl— donde vive el backend (p. ej.https://api.almirant.aipara SaaS ohttps://miempresa.com/apipara self-hosted).appBaseUrl— donde vive el frontend.id— identificador estable de la cuenta, usado por configuraciones generadas.label— alias local humano (local-m1pro,prod-saas,kroko-dev).apiKey— token que el CLI usa para autenticarse contra el backend.
Comandos como init, link o config trabajan sobre una cuenta activa. Puedes alternar entre varias con almirant use <label> o con el selector interactivo de almirant use.
2. Stack self-hosted (~/.almirant/stack/)
Si instalas Almirant en tu servidor, el CLI clona el codigo fuente en ~/.almirant/stack/ y arranca los contenedores con Docker Compose. Todos los comandos ps, logs, down, upgrade asumen ese directorio por defecto (cambiable con --dir).
El stack local y las cuentas son independientes: puedes tener un stack self-hosted corriendo y al mismo tiempo cuentas configuradas contra el SaaS, sin conflicto.
3. Proyecto vinculado (.mcp.json + .agents/)
Cuando ejecutas almirant init o almirant link en la raiz de un repositorio, el CLI escribe dos cosas en ese repo:
.mcp.json— configuracion MCP secretless. No contiene tokens: ejecutaalmirant mcp proxy, que lee la cuenta desde~/.almirant/config.jsony adjunta el bearer token en memoria..agents/y.claude/skills/— plantillas de skills para que los agentes sepan como interactuar con Almirant.
Nada de esto modifica la base de datos de Almirant: es solo metadatos locales del repositorio.
Donde ir ahora
- Si tu equipo ya tiene una cuenta en Almirant (SaaS o instancia desplegada) y solo quieres conectar tu repo: Conectar un repositorio.
- Si quieres levantar Almirant en un servidor propio desde cero: Instalacion self-hosted.
- Si ya tienes el stack corriendo y quieres saber como operarlo en el dia a dia: Operar el stack.
- Si necesitas ver un comando concreto: Referencia de comandos.