Référence CLI

Le CLI cradle — un client HTTP fin pour cradle-server, sa config et le catalogue complet des commandes.

Le CLI cradle est un client HTTP fin qui dialogue avec cradle-server. Il ne touche jamais directement à la base de données et ne charge jamais de runners de modèles — chaque commande est un appel HTTP contre l'API admin.

cradle <sous-commande>

Fichier de configuration

La configuration vit dans ~/.cradle/cli-config.json (remplacez l'emplacement avec $CRADLE_CONFIG_DIR) :

{
  "servers": {
    "default":    { "url": "http://127.0.0.1:31416", "apiKey": "ck_live_…" },
    "production": { "url": "https://cradle.company.local", "apiKey": "ck_live_…" }
  },
  "currentServer": "default",
  "currentProject": "personal"
}

cradle login --url <url> --key <clé> [--name <profil>] écrit un serveur, le définit comme courant, et sonde /admin/health pour vérifier. cradle servers list / use / remove change de profil.

Changement de projet

Chaque requête porte l'en-tête X-Cradle-Project: <currentProject> depuis la config. cradle projects use <slug> met à jour cet en-tête localement. Les clés admin peuvent outrepasser le binding ; les clés scopées doivent utiliser le projet auquel elles sont liées (le serveur renvoie 403 en cas de mismatch).

Modes de sortie

--json transforme chaque commande en un flux JSON propre adapté à jq :

cradle agents execute <id> --text "ping" --json | jq '.replies[0].text'
cradle keys list --json | jq '.[] | select(.scopes | contains(["admin:*"]))'
cradle models list --json | jq '.system.totalRamGb'

Sans --json, la sortie est un tableau texte coloré et aligné.

Catalogue de commandes

cradle init               # sauvegarde la config + vérifie la santé
cradle login              # sauvegarde les credentials serveur
cradle servers            # list / use / remove

cradle server init        # bootstrap un cradle-server headless (systemd, piloté par opérateur)
cradle server package     # construit un zip déployable pour un hôte Linux cible

cradle remote show        # config nœud GPU distant et commandes opérateur
cradle remote set         # configure un nœud GPU distant (pas de push SSH)
cradle remote pool probe  # sonde tous les nœuds du pool pour leur santé
cradle remote pool plan   # plan autoscaler (piloté par opérateur, pas d'exécution)

cradle tenants list              # registre de tenants single-host
cradle tenants create <id>       # bootstrap une nouvelle instance tenant
cradle tenants start <id>        # systemctl start cradle-server-<id>
cradle tenants stop <id>         # systemctl stop cradle-server-<id>
cradle tenants credentials <id>  # affiche client-credentials.json pour un tenant

cradle health             # sonde /admin/health

cradle projects list      # tous les projets du serveur
cradle projects create <slug> [--name --description]
cradle projects use <slug>                   # local — envoie X-Cradle-Project au prochain appel

cradle agents list                           # filtré par projet courant
cradle agents show <id>
cradle agents execute <id> --text "…"        # one-shot, renvoie {replies:[…]}
cradle agents create --template <slug>       # utilise les templates d'agent intégrés

cradle kb list                               # bases de connaissances du projet courant

cradle models list                           # catalogue + installés + verdict compat

cradle models list --recommended             # meilleurs choix du OpenLLM leaderboard
cradle models check <catalogId>              # verdict matériel pour un modèle
cradle models pull <catalogId>               # téléchargement streamé SSE

cradle keys list                             # toutes les clés API (pas de plaintext)
cradle keys create --name … --scopes a:b,c:d --project <id>   # plaintext affiché UNE SEULE FOIS
cradle keys revoke <id>                       # suppression logique

cradle tickets list [--status pending]
cradle tickets show <id>

cradle channels list                          # filtré par projet courant

cradle completion bash                        # script de completion shell

Les commandes d'écriture refusent gracieusement quand un endpoint serveur n'est pas encore implémenté : elles affichent not implemented … (Phase N+) et sortent avec le code 2 — jamais un no-op silencieux.

Bootstrap serveur (`cradle server init`)

C'est la manière pilotée par l'opérateur de déployer un cradle-server headless sur une machine distante (jump host / contour fermé). Le CLI ne pousse jamais par SSH ; l'opérateur l'exécute sur le serveur cible.

# sur le serveur cible, en root :
cradle server init \
  --data-dir /var/lib/cradle/tenant-a \
  --port 31416 \
  --bind 0.0.0.0 \
  --service-name cradle-server-tenant-a

Il crée le répertoire de données, bootstrap la DB SQLite et la première clé admin:*, écrit et active une unité systemd, attend /admin/health, et écrit client-credentials.json (mode 0600) dans le répertoire de données. Le relancer sur le même répertoire est idempotent.

Drapeaux clés

Drapeau	Défaut	Objectif
`--data-dir`	`/var/lib/cradle`	DB SQLite, modèles, fichier credentials
`--port`	`31416`	Port API HTTP
`--bind`	`0.0.0.0`	Hôte de bind (`127.0.0.1` pour local uniquement)
`--user`	`cradle`	Utilisateur OS pour le service systemd
`--service-name`	`cradle-server`	Nom de l'unité systemd
`--skip-systemd`	`false`	Bootstrap uniquement la DB, pas de service
`--dry-run`	`false`	Affiche le plan sans toucher au système
`--scopes`	`admin:*`	Scopes pour la clé client générée

Mode dev / sans systemd

cradle server init --data-dir /tmp/cradle-test --skip-systemd

Cela bootstrap la DB et écrit la clé admin bootstrap dans client-credentials.json sans démarrer de service. Démarrez le serveur manuellement avec cradle-server --data-dir /tmp/cradle-test.

GPU distant (`cradle remote`)

Configurez un nœud llama.cpp / vLLM distant sans pousser de commandes depuis le client. cradle remote set stocke seulement la configuration ; les commandes SSH réelles sont imprimées pour que l'opérateur les exécute sur la jump host.

cradle remote set \
  --host gpu-1.local --user cradle \
  --ssh-key-path /root/.ssh/gpu-1 \
  --remote-port 8080 --model-path /models/qwen3-8b.gguf

cradle remote show

Pour plusieurs nœuds, cradle remote pool probe sonde la santé de chaque nœud et cradle remote pool plan affiche un plan de scale-up / scale-down avec les commandes opérateur à exécuter. L'autoscaler n'exécute jamais lui-même de SSH ou d'appels cloud.

Bash completion

cradle completion bash > /usr/local/etc/bash_completion.d/cradle
# ou par utilisateur :
cradle completion bash >> ~/.bashrc

Le script de completion couvre les commandes de premier niveau et un niveau de sous-commandes.

Référence CLI

On this page