cmp-Befehlszeilentool

Wo im Portal: Die Installationsbefehle befinden sich in der API-Referenz (https://<your-domain>/apidoc, Abschnitt Command-line interface). Bestätigen eines Logins: https://<your-domain>/link. Verbundene Geräte: API keys (/api-keys) › Connected apps & devices.

Funktion

cmp ist ein kleines Befehlszeilenprogramm für Ihre Kunden (und für Sie), das jede API-Operation in einen Befehl umwandelt: cmp vm list, cmp vm start <id>, cmp billing invoice list. Es wird zum Zeitpunkt des Release aus dem OpenAPI-Dokument Ihrer Installation erstellt, sodass die Befehle genau zu den von Ihnen aktivierten Funktionen passen. Es handelt sich um eine einzige statische Binärdatei für Linux, macOS und Windows (amd64 und arm64), für die keine weitere Installation erforderlich ist.

Anforderungen

Komponente	Anforderung
Server	Nichts Zusätzliches. Die Release-Pakete befinden sich im NexCMP-Release und werden vom Panel unter https://<your-domain>/cli/ bereitgestellt.
Kundenmaschine	Linux, macOS oder Windows (PowerShell 5.1+). ssh-keygen (OpenSSH 8.0+) wird nur zur Überprüfung der Signatur benötigt.
Anmeldeinformationen	Ein Browser-Login mit Einmalcode oder ein API key.
Netzwerk	HTTPS zu Ihrem Panel. Das CLI verweigert das Senden eines Schlüssels über unverschlüsseltes http://, außer an localhost.

Infrastruktur vorbereiten

Nichts. Das Panel stellt diese Dateien von /cli/ bereit (kein Build oder Upload erforderlich):

Datei	Zweck
install.sh, install.ps1	Installationsprogramme für Linux/macOS und Windows; sie enthalten die Adresse Ihres Panels.
latest.json	Aktuelle Version, Dateiliste, Größen, sha256.
v<version>/cmp_<version>_<os>_<arch>.tar.gz oder .zip	Die Programme: linux amd64/arm64, darwin amd64/arm64/universal, windows amd64/arm64.
v<version>/SHA256SUMS, SHA256SUMS.sig	Prüfsummen und deren ed25519-Signatur.
cmp-cli.pub	Der öffentliche Release-Schlüssel.

Installieren (Kunde)

macOS und Linux:

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

Windows PowerShell:

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

Das Installationsprogramm wählt das Paket für das Betriebssystem und die CPU aus, lädt SHA256SUMS und dessen Signatur herunter, verifiziert die Signatur mit dem im Skript eingebetteten Schlüssel, überprüft den Paket-Hash und installiert cmp in /usr/local/bin (als root) oder ~/.local/bin; unter Windows in %LOCALAPPDATA%\cmp\bin (wird dem Benutzer-PATH hinzugefügt). Schlägt eine Prüfung fehl, wird nichts installiert.

Variable	Bedeutung
CMP_VERSION	Installieren Sie diese Version anstelle der neuesten.
CMP_INSTALL_DIR	Installationsordner.
CMP_REQUIRE_SIGNATURE	1 = abbrechen, wenn die Signatur nicht verifiziert werden kann.
CMP_BASE_URL	Download-Basis (für Mirrors).

Manueller Download und Verifizierung:

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

Anmelden

cmp login

1. Das CLI gibt einen einmaligen Code sowie einen Link (https://cloud.example.com/link?code=WDJB-MJHT) aus, öffnet den Browser und wartet.
2. Melden Sie sich im Browser im Portal an, überprüfen Sie den Client-Namen, das Gerät, die IP und das Land, kreuzen Sie die Berechtigungen (Scopes) an und wählen Sie aus, wie lange der Schlüssel gültig sein soll (Standard: 90 Tage). Berechtigungen, die kostenpflichtig sind oder Daten löschen, sind zunächst nicht angekreuzt. Klicken Sie auf Genehmigen.
3. Das CLI erhält einen eigenen Schlüssel, getrennt von den Schlüsseln, die der Kunde manuell erstellt hat, und speichert ihn in ~/.config/cmp/config.json (Modus 0600; %APPDATA%\cmp unter Windows). Er erscheint unter API keys › Connected apps & devices und kann dort widerrufen werden.

Der Code läuft nach 10 Minuten ab. Die Genehmigung erfordert eine echte, angemeldete Portalsitzung mit einer verifizierten E-Mail — keinen anderen Schlüssel und keine impersonierte Sitzung.

Nützliche Flags: --scopes vm:read,billing:read, --name "build server", --no-browser, --profile, --api-url.

Für CI oder Server ohne Browser verwenden Sie einen Schlüssel aus dem Portal:

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

Befehle verwenden

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

• Pfadparameter sind positionelle Argumente; Query-Parameter und Body-Felder werden zu Kebab-Case-Flags (--start-port 443).
• --data '{"a":1}', --data @file.json oder --data - sendet einen vollständigen JSON-Body; Flags überschreiben dessen Felder.
• cmp help vm firewall add (oder --help) zeigt die Details eines beliebigen Befehls an.

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

Integrierte Befehle: login, logout, whoami, config, api, completion, version, update, help. Alles andere stammt aus dem API-Dokument.

Globale Flags:

Flag	Bedeutung
-o, --output json|table|yaml	Format. Standardmäßig table auf einem Terminal und json bei Weiterleitung (Piping).
--profile, --api-url	Welcher gespeicherte Login und welche Website.
-y, --yes	Bestätigung für destruktive oder kostenpflichtige Befehle überspringen.
--idempotency-key <k>	Den Schlüssel für einen kostenpflichtigen Befehl auswählen.
--retry <n>	Bei HTTP 429 auf Retry-After warten und bis zu n-mal wiederholen.
--timeout <s>	Sekunden, die auf Antwortheader gewartet werden soll (Standard: 60).
--debug	HTTP-Austausch auf stderr anzeigen, wobei Schlüssel maskiert sind.

Befehle, die das Guthaben belasten oder Daten löschen, fragen nach einer Bestätigung und senden bei kostenpflichtigen Aktionen ein automatisch generiertes Idempotency-Key (wird auf stderr ausgegeben, sodass Sie es mit --idempotency-key sicher wiederholen können). Ohne Terminal werden sie abgelehnt, es sei denn, --yes wird angegeben.

Exit-Codes

Code	Bedeutung
0	Erfolg
1	Sonstiger Fehler (Netzwerk, HTTP 4xx/5xx nicht aufgeführt)
2	Verwendungsfehler
3	Nicht autorisiert (401/403)
4	Nicht gefunden (404)
5	Limit überschritten (Rate-Limit, 429)
6	Bestätigung erforderlich oder abgelehnt
130	Unterbrochen

Profile und Umgebung

cmp config listet Profile auf; cmp config use <name> schaltet um; die Kunden eines Resellers nutzen ihre eigene Domain: cmp login --api-url https://shop.example.net --profile shop. Rangfolge: Flag, Umgebung, Konfigurationsdatei. Variablen: 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'

Shell-Vervollständigung: cmp completion bash|zsh|fish|powershell.

Aktualisierung und Deinstallation

cmp version
cmp update --check
cmp update

cmp update lädt latest.json, SHA256SUMS sowie die Signatur herunter, verifiziert die Signatur mit dem im ausgeführten Binary fest einprogrammierten öffentlichen Schlüssel, prüft den Hash des Pakets und ersetzt sich erst danach selbst. Ein Downgrade erfordert --force. Wenn Sie NexCMP aktualisieren, stellt das Panel das CLI-Release bereit, das mit der neuen Version ausgeliefert wird.

Löschen Sie zur Deinstallation das cmp-Binary und das Konfigurationsverzeichnis (cmp config path zeigt es an). Widerrufen Sie den Schlüssel unter API keys, falls das Gerät verloren geht.

Verifizierung

1. cmp version gibt die Version und die API-Dokumentversionsnummer aus.
2. cmp login, im Browser genehmigen, danach zeigt cmp whoami das Profil und die URL Ihres Panels an.
3. cmp vm list gibt Ihre VMs zurück; cmp vm list -o json | jq . zeigt das rohe JSON an.

Limits & Hinweise

• Die Befehlsliste hängt von Ihrem Build ab: Die Pakete werden aus dem OpenAPI-Dokument Ihrer Installation generiert, wenn das Release erstellt wird. Ein in Ihrer Version deaktiviertes Produkt hat daher keinen Befehl. Verwenden Sie cmp api für einen Pfad, den die CLI nicht kennt.
• Die CLI unterliegt der MIT-Lizenz.
• Jedes Paket ist mit einem ed25519-Schlüssel signiert; der Signaturschlüssel ist im Installer und im Binary hinterlegt und wird nicht zum Zeitpunkt des Updates abgerufen.
• Schlüssel sind pro Schlüssel und pro Konto limitiert (siehe REST API).

Fehlerbehebung

Symptom	Ursache	Behebung
curl .../cli/install.sh gibt 404 zurück	Das Release auf dem Server hat keinen CLI-Ordner oder der Host ist nicht in der Lizenz enthalten	Überprüfen Sie https://<domain>/cli/latest.json und die Domain; aktualisieren Sie NexCMP.
"Signatur konnte nicht verifiziert werden"	ssh-keygen fehlt oder ist zu alt	Installieren Sie OpenSSH 8.0+ oder setzen Sie CMP_REQUIRE_SIGNATURE=0 nur, wenn Sie das Risiko eingehen.
cmp login gibt an, dass der Code abgelaufen ist	10 Minuten sind vergangen	Führen Sie cmp login erneut aus.
Exit-Code 3	Schlüssel hat keinen Scope, ist abgelaufen oder wurde widerrufen	cmp whoami; erstellen oder reaktivieren Sie den Schlüssel mit weiteren Scopes.
Exit-Code 6 in einem Skript	Kostenpflichtiger oder destruktiver Befehl ohne Terminal	Fügen Sie --yes (sowie Ihr eigenes --idempotency-key) hinzu.
"refuses to sends a key over http"	Unverschlüsselte HTTP-API-URL	Verwenden Sie https:// oder CMP_ALLOW_HTTP=1 nur für Testumgebungen.
Browser öffnet die falsche Website	--api-url ist für einen Reseller nicht gesetzt	cmp login --api-url https://<reseller-domain>.