NAQUADA
Ouvrir Naquada
Parcours vérifiable

Pont local Rust

Installer et utiliser la CLI Naquada

La CLI est le pont multiplateforme entre votre projet, Codex et la production Naquada. Elle authentifie l’utilisateur, expose le serveur MCP et livre les assets de façon vérifiable.

Installer sur macOS, Windows ou Linux

Téléchargez uniquement une archive signée depuis le canal officiel. Chaque version publique doit fournir les sommes SHA-256.

Canal de téléchargement non configuré

L’opérateur doit définir NEXT_PUBLIC_NAQUADA_CLI_DOWNLOADS_URL vers les artefacts signés avant publication. Cette page n’invente volontairement aucun binaire ni miroir.

Choisissez l’archive correspondant à votre système et à votre architecture, décompressez-la, puis placez le binaire dans un dossier du PATH.

macOS

Terminal
# After downloading the macOS archive
chmod +x ./naquada
sudo install -m 0755 ./naquada /usr/local/bin/naquada

Linux

Terminal
# After downloading the Linux archive
chmod +x ./naquada
sudo install -m 0755 ./naquada /usr/local/bin/naquada

Windows PowerShell

PowerShell
$destination = "$env:LOCALAPPDATA\Naquada\bin"
New-Item -ItemType Directory -Force $destination
Copy-Item .\naquada.exe "$destination\naquada.exe"
[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";$destination",
  "User"
)
Terminal
naquada --version
naquada --help

Vérification

Résultat attendu : les deux commandes affichent une version puis l’aide, sans erreur.

Installation depuis les sources

Réservée aux contributeurs disposant du monorepo et de Rust stable.

Cargo
cargo install --locked --path apps/naquada-cli

Se connecter sans copier de clé secrète

La CLI interactive utilise un code d’appareil, comme les outils IA modernes : aucun mot de passe ne transite par le terminal.

Terminal
naquada login
naquada whoami
  1. La CLI ouvre la page de production Naquada.
  2. Vous vérifiez le code et approuvez l’appareil dans votre compte.
  3. La session courte et son jeton de renouvellement sont enregistrés dans le coffre sécurisé du système.
  4. naquada logout révoque la session distante puis efface la copie locale.

Ne créez pas de clé globale pour la CLI

La CLI et l’extension VS Code utilisent la connexion par appareil. Les clés globales de compte servent aux intégrations sans utilisateur, aux serveurs et aux scripts.

Lier le dossier courant

La liaison crée un contexte de projet Naquada et les fichiers locaux nécessaires aux reçus. Elle ne parcourt pas le dépôt.

Terminal
naquada project link \
  --name "Mon projet" \
  --tag mon-projet

naquada project status

Résultat concret

  • .naquada/project.json contient l’identifiant et le tag du projet.
  • .naquada/config.json contient uniquement les règles locales.
  • .naquada/runs/ et .naquada/assets/ existent.
  • naquada project status retrouve le même contexte côté production.

Déclarer le serveur MCP à Codex

La commande enregistre le binaire courant comme serveur MCP stdio pour le workspace. Elle utilise la commande officielle codex mcp add.

Terminal
naquada setup codex --apply

Vérification

Rechargez Codex, ouvrez sa liste de serveurs MCP et vérifiez que naquada est activé.

Référence rapide des commandes

Ajoutez --json avant la sous-commande pour obtenir une sortie stable destinée aux extensions et aux scripts.

naquada login / logout / whoamiGérer la session utilisateur.
naquada project linkCréer ou rattacher le contexte du projet.
naquada project statusComparer la liaison locale et distante.
naquada run listLister les reçus locaux.
naquada run status <id>Voir le statut distant et le reçu local.
naquada run resume <id>Reprendre une livraison approuvée.
naquada run cancel <id>Demander l’annulation du run.
naquada mcp serveDémarrer le serveur MCP stdio.
naquada setup codex --applyEnregistrer le serveur dans Codex.
naquada docsOuvrir cette documentation publique.
naquada doctorContrôler session, projet, API et dossiers.

Livraison et reprise des assets

Une exécution distante et une livraison locale sont deux étapes distinctes. Le reçu rend la seconde idempotente.

  • Les références locales sont hachées et envoyées uniquement si le plan les nomme.
  • Un asset est téléchargé dans .naquada/assets/, contrôlé en taille et SHA-256, puis déplacé.
  • Le chemin final doit rester dans la racine du workspace.
  • Sans ordre explicite d’écrasement, la stratégie renomme le doublon avec -02, -03, etc.
  • Après un redémarrage, run resume reprend le téléchargement grâce au reçu.
  • Aucune opération Git n’est exécutée.
Terminal
naquada run list
naquada run status <run-id>
naquada run resume <run-id>

Sessions, clés globales et clés de publication

Naquada sépare volontairement trois types de credentials afin d’éviter qu’une clé trop puissante circule partout.

1

Session CLI / extension

Connexion par appareil, jetons courts renouvelables, stockage dans le coffre du système et révocation à la déconnexion.

2

Clé globale de compte — préfixe nqk_acc_

Pour une automatisation sans interface. Vous choisissez des droits fins : lecture/modification limitée du compte, lecture/création de boards, lecture/création/exécution de publications. Le secret n’est montré qu’une fois ; la clé a une expiration, une limite et peut être révoquée immédiatement.

Account API
curl https://api.naquada.tech/api/account/v1/capabilities \
  -H "Authorization: Bearer $NAQUADA_ACCOUNT_KEY"
3

Clé de publication — préfixe ctr_prd_ ou ctr_sbx_

Son comportement Sandbox/Production ne change pas. Une clé globale ne peut l’utiliser que si elle possède externalizations:invoke, si sa politique autorise cette clé Production et si l’appel fournit X-Naquada-Externalization-Key-Id. Le secret de la clé de publication n’est jamais exposé.

Delegated publication
curl "https://api.naquada.tech/api/v1/generate/my-slug?version=1" \
  -H "Authorization: Bearer $NAQUADA_ACCOUNT_KEY" \
  -H "X-Naquada-Externalization-Key-Id: <production-key-id>" \
  -H "Content-Type: application/json" \
  -d '{"inputs":{"prompt":"Bonjour"}}'

Rotation recommandée

Créez une nouvelle clé globale avec la même politique, déployez-la, vérifiez sa dernière utilisation, puis révoquez et supprimez l’ancienne. Les permissions et la délégation restent immuables après création.

Diagnostic et résultat attendu

Le rapport JSON permet à une extension ou à un humain de constater chaque précondition.

Terminal
naquada --json doctor

Résultat

Le système est prêt lorsque ok, authenticated, projectLinked et apiReachable valent true, que les chemins pointent vers le projet courant et que gitTouched vaut false.