Connecter un dépôt

Ce flux est le plus courant : vous avez un compte Almirant (SaaS ou self-hosted) et souhaitez que votre dépôt local apparaisse comme un projet, avec des agents IA accessibles depuis votre IDE (Claude Code, Codex, OpenCode, Cursor, etc.).

Temps estimé : 2 minutes.

Prérequis

• Le CLI installé (bun add -g almirant@latest ou npm i -g almirant).
• Un compte Almirant. Si vous n'en avez pas encore, créez-en un sur almirant.ai ou déployez votre propre instance en suivant le guide self-hosted.

Étape 1 — Vous authentifier

Choisissez la commande selon le backend auprès duquel vous vous authentifiez :

# SaaS
almirant login

# Instancia self-hosted
almirant login --api-url https://almirant.miempresa.com/api

Le CLI ouvre le navigateur pour OAuth et enregistre le compte dans ~/.almirant/config.json avec les permissions 600.

astuce

Vous ne devez exécuter login qu'une fois par backend. Si vous travaillez avec plusieurs instances (par exemple SaaS et self-hosted à la fois), exécutez almirant login une fois pour chacune, attribuez-leur des labels avec almirant accounts rename, puis changez de compte actif avec almirant use. Consultez Travailler avec plusieurs comptes.

Étape 2 — Choisir le compte actif

Si vous avez plusieurs comptes, utilisez des labels. Dans quatre mois, vous vous souviendrez de local-m1pro, pas d'une longue URL.

almirant accounts list
almirant accounts rename 1 prod-saas
almirant accounts rename 2 local-m1pro
almirant use local-m1pro
almirant current

Étape 3 — Lier le dépôt

Accédez à la racine du dépôt que vous souhaitez connecter et exécutez :

cd mi-repo
almirant link

Le CLI :

1. Lit vos comptes enregistrés et utilise le compte actif ou vous laisse en choisir un.
2. Liste les projets de ce compte et vous permet d'en choisir un ou d'en créer un nouveau.
3. Fusionne une entrée almirant dans .mcp.json à l'aide du proxy stdio local.
4. Copie les modèles de skills dans .claude/skills/ et .agents/skills/.

S'il s'agit de votre première fois et que vous n'avez pas encore exécuté almirant login, utilisez almirant init au lieu de link : init déclenche également le flux OAuth dans la même commande.

Étape 4 — Vérifier dans votre IDE

Ouvrez le dépôt dans votre agent et demandez par exemple :

Liste mes work items Almirant

Si vous voyez la liste, tout est connecté. Si vous obtenez Unauthorized, vérifiez :

• Que .mcp.json existe à la racine du dépôt.
• Que le --account de .mcp.json pointe vers un compte existant (almirant accounts list).
• Que la clé API locale est toujours valide (almirant current n'affiche que le préfixe, pas le secret).
• Que le backend est démarré et accessible, en particulier s'il est self-hosted.

Ce qui reste dans votre dépôt

Après link, votre dépôt contient :

mi-repo/
├── .mcp.json              ← arranca almirant mcp proxy; no contiene tokens
├── .claude/
│   └── skills/            ← plantillas de skills para Claude Code
└── .agents/
    └── skills/            ← mismo contenido, para agentes no-Claude

L'entrée MCP générée suit ce modèle :

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

info

La clé API se trouve dans ~/.almirant/config.json, et non dans .mcp.json. Le proxy attache le bearer token en mémoire lorsque l'agent le démarre.

Codex .codex/config.toml

Si vous utilisez Codex et que le serveur MCP est déclaré dans .codex/config.toml, utilisez le même proxy :

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

N'écrivez pas de bearer tokens dans .codex/config.toml. Si vous souhaitez que ce dépôt utilise toujours le compte actif, omettez --account ; pour le travail en équipe ou les anciens dépôts, nous préférons le fixer par ID.

Migrer depuis d'anciennes configurations

Si votre .mcp.json contient type: "http", url et Authorization: Bearer ..., réexécutez :

almirant link

Si ce token a déjà été présent dans git, faites-le pivoter :

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

Gérer plusieurs comptes et projets

Si vous travaillez avec plusieurs comptes (cas typique : compte personnel + entreprise, ou SaaS + instance interne), consultez Travailler avec plusieurs comptes.

Pour modifier le projet lié d'un dépôt déjà initialisé, réexécutez almirant link et choisissez le nouveau projet : le CLI réécrit l'entrée almirant de .mcp.json tout en conservant les autres serveurs.