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

tip

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.ai para SaaS o https://miempresa.com/api para 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: ejecuta almirant mcp proxy, que lee la cuenta desde ~/.almirant/config.json y 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.