CLI-Überblick

Das Almirant CLI (almirant) ist ein einheitliches Werkzeug für zwei Arten von Nutzern:

• SaaS-Teams, die ihr lokales Repository mit einem Almirant-Projekt verbinden und KI-Agenten aus ihrer IDE verwenden möchten.
• Self-Hoster, die eine eigene Almirant-Instanz auf Docker installieren, aktualisieren und betreiben möchten.

Beide Abläufe verwenden dieselbe Binary und dieselbe Konfigurationsdatei. Nur die verwendeten Befehle unterscheiden sich.

Was du tun kannst

Aufgabe	Befehl	Anleitung
Dich bei einem Almirant-Backend authentifizieren	almirant login	Ein Repository verbinden
Das aktuelle Verzeichnis mit einem Projekt verbinden	almirant init / almirant link	Ein Repository verbinden
Eine Self-Hosted-Instanz installieren	almirant install	Self-Hosted-Installation
Den Status des lokalen Stacks anzeigen	almirant ps	Den Stack betreiben
Logs des lokalen Stacks lesen	almirant logs	Den Stack betreiben
Den lokalen Stack anhalten	almirant down	Den Stack betreiben
Den Stack aktualisieren	almirant upgrade	Den Stack betreiben
Konten verwalten (SaaS, Self-Hosted)	almirant accounts / almirant use	Mehrere Konten

Das CLI installieren

Das CLI wird als npm-Paket verteilt (eine eigenständige, in Go geschriebene Binary):

bun add -g almirant@latest
# o
npm i -g almirant

Überprüfe die Installation:

almirant version

Tipp

Wenn du nur ein Repository mit einem SaaS-Projekt verbinden möchtest, ist Ein Repository verbinden die kürzeste Anleitung. Du brauchst nichts weiter.

Mentales Modell

Um die Ausgabe eines Befehls zu verstehen, behalte diese drei Konzepte im Kopf:

1. Konten (~/.almirant/config.json)

Das CLI speichert ein oder mehrere Konten. Jedes Konto ist ein Tupel aus:

• apiBaseUrl — hier befindet sich das Backend (z. B. https://api.almirant.ai für SaaS oder https://miempresa.com/api für Self-Hosted).
• appBaseUrl — hier befindet sich das Frontend.
• id — stabile Kennung des Kontos, die von generierten Konfigurationen verwendet wird.
• label — lokaler, lesbarer Alias (local-m1pro, prod-saas, kroko-dev).
• apiKey — Token, das das CLI zur Authentifizierung beim Backend verwendet.

Befehle wie init, link oder config arbeiten mit einem aktiven Konto. Du kannst mit almirant use <label> oder dem interaktiven Selektor von almirant use zwischen mehreren Konten wechseln.

2. Self-Hosted-Stack (~/.almirant/stack/)

Wenn du Almirant auf deinem Server installierst, klont das CLI den Quellcode nach ~/.almirant/stack/ und startet die Container mit Docker Compose. Alle Befehle ps, logs, down und upgrade verwenden dieses Verzeichnis standardmäßig (mit --dir änderbar).

Der lokale Stack und die Konten sind unabhängig: Du kannst einen laufenden Self-Hosted-Stack haben und gleichzeitig Konten für SaaS konfiguriert haben, ohne Konflikte.

3. Verbundenes Projekt (.mcp.json + .agents/)

Wenn du almirant init oder almirant link im Stammverzeichnis eines Repositorys ausführst, schreibt das CLI zwei Dinge in dieses Repository:

• .mcp.json — tokenlose MCP-Konfiguration. Sie enthält keine Tokens: Sie führt almirant mcp proxy aus, das das Konto aus ~/.almirant/config.json liest und das Bearer-Token im Speicher anhängt.
• .agents/ und .claude/skills/ — Skill-Vorlagen, damit Agenten wissen, wie sie mit Almirant interagieren.

Nichts davon verändert die Almirant-Datenbank: Es handelt sich nur um lokale Metadaten des Repositorys.

Wie es weitergeht

• Wenn dein Team bereits ein Almirant-Konto hat (SaaS oder bereitgestellte Instanz) und du nur dein Repository verbinden möchtest: Ein Repository verbinden.
• Wenn du Almirant von Grund auf auf einem eigenen Server starten möchtest: Self-Hosted-Installation.
• Wenn der Stack bereits läuft und du wissen möchtest, wie du ihn täglich betreibst: Den Stack betreiben.
• Wenn du einen bestimmten Befehl nachschlagen musst: Befehlsreferenz.