Referencia de comandos

Lista exhaustiva de los comandos del CLI. Para ver la ayuda inline en cualquier momento:

almirant --help
almirant <comando> --help

---

almirant install

Instala una instancia self-hosted de Almirant en la maquina actual.

Clona el repo fuente en --dir (default ~/.almirant/stack) y ejecuta el script scripts/install.sh que construye las imagenes Docker, genera .env.production con secretos aleatorios, y arranca el stack.

almirant install [flags]

Flag	Default	Descripcion
--branch	main	Rama o tag de git a instalar
--dir	~/.almirant/stack	Directorio donde clonar el stack
--from-dir	—	Usa un clone local ya existente (instalacion air-gapped, el CLI no toca git)
--non-interactive	false	Omite los prompts del instalador (usa defaults)
--public-url	—	URL publica donde se servira Almirant (sin slash final)
--repo	almirant-ai/almirant	Repo de GitHub a clonar
--with-discord	false	Activa el profile de Discord bridge
--with-proxy	false	Activa el profile de reverse proxy (Caddy)

Comportamiento

• Si --dir ya contiene un clone previo, el CLI hace git fetch + fast-forward pull en --branch en lugar de reclonar.
• El instalador genera .env.production solo la primera vez. Si el archivo ya existe, lo conserva tal cual (tus secretos se mantienen).
• El --public-url se escribe a la vez en NEXT_PUBLIC_SITE_URL, BETTER_AUTH_URL, BETTER_AUTH_TRUSTED_ORIGINS y CORS_ORIGIN. Cambiar esa URL mas tarde requiere reconstruir el frontend (ver Operar el stack).

Ejemplos

# Instalacion interactiva, te pregunta la URL publica
almirant install

# Instalacion sin prompts, con URL fijada
almirant install --non-interactive --public-url https://almirant.example.com

# Instalacion desde un tag concreto
almirant install --branch v1.2.3

# Instalacion air-gapped desde un clone existente
almirant install --from-dir /opt/almirant-release --non-interactive

nota

El instalador tiene que correr en la maquina destino. No hay modo remoto via SSH en install — para eso usa almirant upgrade --host <ssh> sobre un stack ya instalado.

---

almirant login

Abre el navegador para completar un flujo OAuth contra el backend de Almirant, captura la API key generada y guarda una cuenta en ~/.almirant/config.json.

almirant login [flags]

Flag	Default	Descripcion
--api-url	prompt	URL base del API (sobreescribe ALMIRANT_API_URL y el prompt)
--app-url	derivada de --api-url	URL base del frontend
--name	Almirant CLI	Etiqueta con la que se guardara la API key en el backend

Cada login crea o actualiza una cuenta local con ID estable y label humano. Puedes repetirlo para SaaS, staging y varias instancias self-hosted.

almirant login
almirant login --api-url https://almirant.miempresa.com/api
almirant accounts list

tip

Las API keys viven en ~/.almirant/config.json con permisos 600. Los archivos de proyecto generados por init y link no contienen bearer tokens.

---

almirant init

Flujo completo de primer uso en un repositorio. Detecta el tipo de proyecto, deja elegir o crear una cuenta, selecciona o crea un proyecto, y escribe:

• .mcp.json — configuracion MCP secretless que ejecuta almirant mcp proxy.
• .claude/skills/ y .agents/skills/ — plantillas de skills.

almirant init [flags]

Flag	Default	Descripcion
--api-url	—	URL del API (solo cuando se añade una cuenta nueva)
--app-url	—	URL del frontend (solo cuando se añade una cuenta nueva)
--name	Almirant CLI	Etiqueta de la API key (solo cuenta nueva)

Comportamiento

• Si ya tienes cuentas guardadas, init te deja elegir una.
• Si no tienes ninguna cuenta, dispara el flujo OAuth igual que almirant login.
• Si .mcp.json ya existe, fusiona la entrada almirant sin tocar otros servidores MCP.
• La entrada generada usa type: "stdio", command: "almirant" y args: ["mcp", "proxy", ...].

---

almirant link

Igual que init pero sin flujo OAuth. Requiere que ya hayas autenticado al menos una cuenta con almirant login.

almirant link

No acepta flags mas alla de --help. Elige cuenta y proyecto de las que ya tienes guardadas y escribe .mcp.json + skills en el directorio actual.

Cuando usar cada uno

• init — primera vez en un equipo nuevo, o si quieres que el CLI te lleve paso a paso incluyendo el login.
• link — ya autenticaste antes y solo quieres conectar un repo mas a un proyecto existente.

---

almirant accounts

Gestiona cuentas desde el atajo principal. Los mismos subcomandos existen tambien bajo almirant config accounts ... por compatibilidad.

almirant accounts list
almirant accounts rename <ref> <label>
almirant accounts add
almirant accounts remove <ref>
almirant accounts set-default <ref>

Subcomando	Descripcion
list	Lista marker, indice, label, email, API URL y estado de la API key
add	Alias de almirant login
rename <ref> <label>	Cambia el label humano de una cuenta
remove <ref>	Elimina una cuenta local (--yes salta confirmacion)
set-default <ref>	Define la cuenta activa por defecto

<ref> puede ser label, ID estable, email unico o indice 1-based.

almirant use [label|id|email|index]

Selecciona la cuenta activa. Sin argumento abre un selector interactivo.

almirant use local-m1pro
almirant current

almirant current imprime label, ID, email, API URL y prefijo de la key sin exponer el token completo.

almirant mcp proxy

Ejecuta el proxy stdio que usan los agentes MCP.

almirant mcp proxy --project-id <id> [--account <label|id|email|index>]

El proxy lee la cuenta de ~/.almirant/config.json, reenvia el trafico a <apiBaseUrl>/mcp?projectId=<id> y adjunta el bearer token solo en memoria. No escribas tokens en .mcp.json, .codex/config.toml ni archivos de shell.

---

almirant ps

Wrapper sobre docker compose ps contra el archivo de compose de produccion.

almirant ps [flags]

Flag	Default	Descripcion
--dir	~/.almirant/stack	Directorio del stack

---

almirant logs

Wrapper sobre docker compose logs del stack de produccion.

almirant logs [service...] [flags]

Positional args — nombres de servicios a los que limitar la salida (p. ej. backend, frontend, db-init).

Flag	Default	Descripcion
--dir	~/.almirant/stack	Directorio del stack
-f, --follow	false	Seguir la salida en tiempo real (tail -f)
--tail	0 (todo)	Mostrar solo las ultimas N lineas por servicio

Ejemplos

# Todos los servicios, las ultimas 100 lineas
almirant logs --tail 100

# Solo backend y frontend, en tiempo real
almirant logs -f backend frontend

---

almirant down

Ejecuta docker compose down sobre el stack de produccion. Los volumenes de datos se conservan por defecto.

almirant down [flags]

Flag	Default	Descripcion
--dir	~/.almirant/stack	Directorio del stack
--rmi	—	Tambien borra imagenes. Valores: local o all
--volumes	false	Destructivo: tambien borra los volumenes (pierdes todos los datos)

aviso

--volumes es irreversible. Solo usalo si quieres empezar desde cero. Para un test limpio tras un install fallido, tipicamente quieres: almirant down --volumes.

---

almirant upgrade

Actualiza el stack a la version mas reciente del branch indicado.

Modo local (sin --host): hace git fetch + pull en --dir, reconstruye las imagenes y reinicia los contenedores.

Modo remoto (con --host): ejecuta scripts/update-remote.sh contra la maquina via SSH.

almirant upgrade [service...] [flags]

Positional args — nombres de servicios a los que limitar el rebuild (p. ej. frontend backend). Si los omites, reconstruye todo.

Flag	Default	Descripcion
--branch	main	Branch a traer
--dir	~/.almirant/stack	Directorio del stack (modo local)
--host	—	SSH host para upgrade remoto
--local-repo	—	Path a un clone local para evitar la descarga del script (modo remoto)
--repo	almirant-ai/almirant	Repo del script de upgrade (modo remoto)

Ejemplos

# Upgrade completo del stack local
almirant upgrade

# Solo reconstruir el frontend (mas rapido si solo cambiaste UI)
almirant upgrade frontend

# Upgrade de un servidor remoto via SSH
almirant upgrade --host [email protected]

---

almirant config

Gestiona la configuracion del CLI guardada en ~/.almirant/config.json. Para el dia a dia, prefiere los atajos almirant accounts, almirant use y almirant current; config conserva el arbol completo y subcomandos avanzados.

almirant config [comando]

almirant config show

Imprime todas las cuentas configuradas sin exponer secretos. La API key se muestra solo por su prefijo (p. ej. alm_k1_…). La clave completa nunca se imprime.

almirant config accounts

Alias completo del gestor de cuentas. Tambien disponible como almirant accounts ....

Subcomando	Descripcion
list	Lista todas las cuentas configuradas
add	Alias de almirant login — añade una cuenta nueva
rename <ref> <label>	Renombra el label humano de una cuenta
remove <ref>	Elimina una cuenta del config local
set-default <ref>	Define cual es la cuenta activa por defecto

almirant config set

Subcomando	Descripcion
api-url <url> [--account <ref>]	Cambia la URL del API de una cuenta (util si el backend se movio)

almirant config rotate

Subcomando	Descripcion
api-key [--account <ref>]	Genera una API key nueva para la cuenta seleccionada y sustituye la anterior. La clave anterior queda invalidada en el servidor.

almirant config reset

Borra todas las cuentas y deja el config vacio.

almirant config reset       # te pide confirmacion
almirant config reset -y    # sin prompt, para scripts

---

almirant version

Imprime la version del CLI y el metadata del build.

almirant version

Util para reportar issues y para decidir si merece la pena actualizar con bun add -g almirant@latest.

---

Variables de entorno

Varios comandos respetan variables de entorno equivalentes a sus flags. Las listamos aqui porque son utiles en CI y scripts.

Variable	Comando afectado	Equivalente a flag
ALMIRANT_API_URL	login, init	--api-url
ALMIRANT_APP_URL	login, init	--app-url
ALMIRANT_NONINTERACTIVE	install (via scripts/install.sh)	--non-interactive
ALMIRANT_PUBLIC_URL	install (via scripts/install.sh)	--public-url
ALMIRANT_WITH_PROXY	install	--with-proxy
ALMIRANT_WITH_DISCORD	install	--with-discord