Outil en ligne de commande cmp

Où se trouve l'élément dans le portail : les commandes d'installation se trouvent sur la référence API (https://<your-domain>/apidoc, section Command-line interface). Approbation d'une connexion : https://<your-domain>/link. Appareils connectés : API keys (/api-keys) › Connected apps & devices.

Description

cmp est un petit programme en ligne de commande destiné à vos clients (et à vous-même) qui transforme chaque opération de l'API en commande : cmp vm list, cmp vm start <id>, cmp billing invoice list. Il est généré à partir du document OpenAPI de votre installation lors de la publication, de sorte que les commandes correspondent aux fonctionnalités que vous avez activées. Il s'agit d'un binaire statique unique pour Linux, macOS et Windows (amd64 et arm64) sans autre dépendance à installer.

Prérequis

Élément	Prérequis
Serveur	Rien de plus. Les paquets de publication sont inclus dans la version de NexCMP et servis par le panneau à l'adresse https://<your-domain>/cli/.
Machine client	Linux, macOS ou Windows (PowerShell 5.1+). ssh-keygen (OpenSSH 8.0+) est requis uniquement pour vérifier la signature.
Identifiants	Une connexion par navigateur avec un code à usage unique, ou une API key.
Réseau	HTTPS vers votre panel. Le CLI refuse d'envoyer une clé en clair sur http:// sauf vers localhost.

Préparer l'infrastructure

Rien. Le panel sert ces fichiers depuis /cli/ (aucune compilation ni aucun téléversement requis) :

Fichier	Usage
install.sh, install.ps1	Installateurs pour Linux/macOS et Windows ; ils contiennent l'adresse de votre panel.
latest.json	Version actuelle, liste des fichiers, tailles, sha256.
v<version>/cmp_<version>_<os>_<arch>.tar.gz ou .zip	Les programmes : linux amd64/arm64, darwin amd64/arm64/universal, windows amd64/arm64.
v<version>/SHA256SUMS, SHA256SUMS.sig	Sommes de contrôle et leur signature ed25519.
cmp-cli.pub	La clé publique de la version.

Installer (client)

macOS et Linux :

curl -fsSL https://cloud.example.com/cli/install.sh | sh

Windows PowerShell :

irm https://cloud.example.com/cli/install.ps1 | iex

L'installateur sélectionne le paquet correspondant au système et au processeur, télécharge SHA256SUMS et sa signature, vérifie la signature avec la clé intégrée au script, vérifie le hachage du paquet et installe cmp dans /usr/local/bin (en tant que root) ou ~/.local/bin ; sous Windows, dans %LOCALAPPDATA%\cmp\bin (ajouté au PATH de l'utilisateur). Si une vérification échoue, rien n'est installé.

Variable	Description
CMP_VERSION	Installer cette version au lieu de la plus récente.
CMP_INSTALL_DIR	Dossier d'installation.
CMP_REQUIRE_SIGNATURE	1 = abandonner lorsque la signature ne peut pas être vérifiée.
CMP_BASE_URL	Base de téléchargement (pour les miroirs).

Téléchargement et vérification manuels :

curl -fsSLO https://cloud.example.com/cli/latest.json
sha256sum --check --ignore-missing SHA256SUMS

Connexion

cmp login

1. Le CLI affiche un code à usage unique et un lien (https://cloud.example.com/link?code=WDJB-MJHT), ouvre le navigateur et patiente.
2. Dans le navigateur, connectez-vous au portail, vérifiez le nom du client, l'appareil, l'adresse IP et le pays, cochez les autorisations (scopes) et choisissez la durée de vie de la clé (par défaut 90 jours). Les autorisations payantes ou supprimant des données restent décochées par défaut. Cliquez sur approuver.
3. Le CLI reçoit sa propre clé, distincte de celles créées manuellement par le client, et la stocke dans ~/.config/cmp/config.json (mode 0600 ; %APPDATA%\cmp sous Windows). Elle apparaît sous API keys › Connected apps & devices et peut y être révoquée.

Le code expire après 10 minutes. L'approbation nécessite une véritable session de portail connectée avec un e-mail vérifié — pas une autre clé ni une session usurpée.

Options utiles : --scopes vm:read,billing:read, --name "build server", --no-browser, --profile, --api-url.

Pour l'intégration continue ou les serveurs sans navigateur, utilisez une clé provenant du portail :

printf %s "$KEY" | cmp login --with-token
export CMP_TOKEN=vk_XXXX      # nothing is written to disk
cmp whoami

Utilisation des commandes

cmp <group> [subgroup] <action> [<id> ...] [flags]

• Les paramètres de chemin sont des arguments positionnels ; les paramètres de requête et les champs de corps deviennent des options en kebab-case (--start-port 443).
• --data '{"a":1}', --data @file.json ou --data - envoie un corps JSON complet ; les options remplacent ses champs.
• cmp help vm firewall add (ou --help) affiche les détails de n'importe quelle commande.

cmp catalog plans
cmp vm list --state active --per-page 50
cmp vm get 3f2a1c9e-0000-4000-8000-000000000000
cmp vm start 3f2a1c9e-0000-4000-8000-000000000000
cmp vm firewall add 3f2a1c9e-... --protocol tcp --start-port 22 --cidr-list 203.0.113.0/24
cmp billing wallet
cmp api GET /v1/vm --query page=2      # raw call to any endpoint

Commandes intégrées : login, logout, whoami, config, api, completion, version, update, help. Tout le reste provient du document API.

Options globales :

Option	Description
-o, --output json|table|yaml	Format. Par défaut table dans un terminal et json lors d'un tuyautage (pipe).
--profile, --api-url	Connexion enregistrée et site utilisés.
-y, --yes	Ignorer la confirmation pour les commandes destructrices ou payantes.
--idempotency-key <k>	Choisir la clé d'une commande payante.
--retry <n>	En cas d'erreur HTTP 429, attendre Retry-After et réessayer jusqu'à n fois.
--timeout <s>	Secondes à attendre pour les en-têtes de réponse (60 par défaut).
--debug	Afficher l'échange HTTP sur stderr, avec les clés masquées.

Les commandes qui facturent le portefeuille ou suppriment des données demandent une confirmation et, si elles sont payantes, envoient un jeton généré automatiquement Idempotency-Key (affiché sur stderr, ce qui vous permet de réessayer en toute sécurité avec --idempotency-key). Sans terminal, elles refusent à moins que --yes ne soit fourni.

Codes de sortie

Code	Description
0	Succès
1	Autre erreur (réseau, HTTP 4xx/5xx non répertorié)
2	Erreur d'utilisation
3	Non autorisé (401/403)
4	Introuvable (404)
5	Limite de taux atteinte (429)
6	Confirmation requise ou refusée
130	Interrompu

Profils et environnement

cmp config liste les profils ; cmp config use <name> bascule ; les clients d'un revendeur utilisent leur propre domaine : cmp login --api-url https://shop.example.net --profile shop. Priorité : indicateur, environnement, fichier de configuration. Variables : CMP_TOKEN, CMP_PROFILE, CMP_API_URL, CMP_OUTPUT, CMP_CONFIG_DIR, CMP_ALLOW_HTTP, CMP_UPDATE_URL.

GitHub Actions :

- name: Install cmp
  run: |
    curl -fsSL https://cloud.example.com/cli/install.sh | CMP_INSTALL_DIR="$RUNNER_TEMP/bin" sh
    echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
- name: List running VMs
  env:
    CMP_TOKEN: ${{ secrets.CMP_TOKEN }}   # a read-only key
  run: cmp vm list -o json | jq -r '.items[] | select(.cs_state=="Running") | .hostname'

Complétion du shell : cmp completion bash|zsh|fish|powershell.

Mise à jour et désinstallation

cmp version
cmp update --check
cmp update

cmp update télécharge latest.json, SHA256SUMS ainsi que la signature, vérifie la signature à l'aide de la clé publique intégrée dans le binaire en cours d'exécution, vérifie le hachage du paquet et ne se remplace qu'ensuite. Une rétrogradation (downgrade) nécessite --force. Lorsque vous mettez à jour NexCMP, le panneau sert la version de la CLI fournie avec la nouvelle version.

Pour désinstaller, supprimez le binaire cmp et le répertoire de configuration (cmp config path l'indique). Révoquez la clé sous API keys si la machine est perdue.

Vérification

1. cmp version affiche la version et la version du document API.
2. cmp login, approuvez dans le navigateur, puis cmp whoami affiche le profil et l'URL de votre panneau.
3. cmp vm list renvoie vos VM ; cmp vm list -o json | jq . affiche le JSON brut.

Limites et notes

• La liste des commandes dépend de votre compilation : les paquets sont générés à partir du document OpenAPI de votre installation lors de la compilation de la version, de sorte qu'un produit désactivé dans votre version ne possède aucune commande. Utilisez cmp api pour un chemin que la CLI ne connaît pas.
• La CLI est sous licence MIT.
• Chaque paquet est signé avec une clé ed25519 ; la clé de signature est intégrée dans l'installateur et le binaire, et n'est pas récupérée au moment de la mise à jour.
• Les clés sont limitées par clé et par compte (voir REST API).

Dépannage

Symptôme	Cause	Solution
curl .../cli/install.sh renvoie 404	La version sur le serveur n'a pas de dossier CLI, ou l'hôte n'est pas couvert par la licence	Vérifiez https://<domain>/cli/latest.json et le domaine ; mettez à jour NexCMP.
"la signature n'a pas pu être vérifiée"	ssh-keygen manquant ou trop ancien	Installez OpenSSH 8.0+, ou définissez CMP_REQUIRE_SIGNATURE=0 uniquement si vous assumez le risque.
cmp login indique que le code a expiré	10 minutes se sont écoulées	Exécutez à nouveau cmp login.
Code de sortie 3	La clé n'a pas de portée, a expiré ou a été révoquée	cmp whoami ; créez ou réapprouvez avec davantage de portées.
Code de sortie 6 dans un script	Commande payante ou destructive sans terminal	Ajoutez --yes (ainsi que votre propre --idempotency-key).
"refuse d'envoyer une clé via http"	URL d'API HTTP simple	Utilisez https://, ou CMP_ALLOW_HTTP=1 uniquement pour un laboratoire.
Le navigateur ouvre le mauvais site	--api-url non défini pour un revendeur	cmp login --api-url https://<reseller-domain>.