Strumento a riga di comando cmp

Dove nel portale: i comandi di installazione si trovano nella documentazione delle API (https://<your-domain>/apidoc, sezione Command-line interface). Approvazione di un accesso: https://<your-domain>/link. Dispositivi connessi: API keys (/api-keys) › Connected apps & devices.

Descrizione

cmp è un piccolo programma a riga di comando per i tuoi clienti (e per te) che trasforma ogni operazione API in un comando: cmp vm list, cmp vm start <id>, cmp billing invoice list. Viene generato dal documento OpenAPI della tua installazione al momento del rilascio, in modo che i comandi corrispondano alle funzioni abilitate. Si tratta di un unico eseguibile statico per Linux, macOS e Windows (amd64 e arm64) che non richiede altro.

Requisiti

Elemento	Requisito
Server	Niente di extra. I pacchetti di rilascio si trovano all'interno della release di NexCMP e vengono serviti dal pannello a https://<your-domain>/cli/.
Macchina del cliente	Linux, macOS o Windows (PowerShell 5.1+). ssh-keygen (OpenSSH 8.0+) serve solo per verificare la firma.
Credenziali	Accesso via browser con codice monouso o una API key.
Rete	HTTPS verso il pannello. La CLI rifiuta di inviare una chiave su connessioni non protette http://, eccetto verso localhost.

Prepara l'infrastruttura

Nulla. Il pannello distribuisce questi file da /cli/ (senza alcuna compilazione o caricamento):

File	Scopo
install.sh, install.ps1	Programmi di installazione per Linux/macOS e Windows; contengono l'indirizzo del tuo pannello.
latest.json	Versione corrente, elenco dei file, dimensioni, sha256.
v<version>/cmp_<version>_<os>_<arch>.tar.gz o .zip	I programmi: linux amd64/arm64, darwin amd64/arm64/universal, windows amd64/arm64.
v<version>/SHA256SUMS, SHA256SUMS.sig	Checksum e relativa firma ed25519.
cmp-cli.pub	La chiave pubblica della release.

Installazione (cliente)

macOS e Linux:

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

Windows PowerShell:

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

L'installer seleziona il pacchetto per il sistema operativo e la CPU, scarica SHA256SUMS e la sua firma, verifica la firma con la chiave integrata nello script, verifica l'hash del pacchetto e installa cmp in /usr/local/bin (come root) o in ~/.local/bin; su Windows in %LOCALAPPDATA%\cmp\bin (aggiunto alla variabile PATH dell'utente). Se un controllo fallisce, non viene installato nulla.

Variabile	Significato
CMP_VERSION	Installa questa versione invece della più recente.
CMP_INSTALL_DIR	Cartella di installazione.
CMP_REQUIRE_SIGNATURE	1 = interrompe l'operazione se la firma non può essere verificata.
CMP_BASE_URL	Base di download (per i mirror).

Download manuale e verifica:

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

Accesso

cmp login

1. La CLI stampa un codice monouso e un link (https://cloud.example.com/link?code=WDJB-MJHT), apre il browser e rimane in attesa.
2. Nel browser accedi al portale, controlla il nome del client, il dispositivo, l'IP e il paese, seleziona i permessi (scope) e scegli la durata della chiave (predefinita 90 giorni). I permessi che comportano costi o eliminano dati sono inizialmente deselezionati. Fai clic su approva.
3. La CLI riceve la propria chiave, separata da quelle create manualmente dal cliente, e la memorizza in ~/.config/cmp/config.json (modalità 0600; %APPDATA%\cmp su Windows). Viene visualizzata in API keys › Connected apps & devices e può essere revocata da lì.

Il codice scade dopo 10 minuti. L'approvazione richiede una sessione autenticata reale nel portale con un'e-mail verificata — non un'altra chiave né una sessione impersonata.

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

Per la CI o per server senza browser, usa una chiave del portale:

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

Uso dei comandi

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

• I parametri di percorso sono argomenti posizionali; i parametri di query e i campi del body diventano flag in kebab-case (--start-port 443).
• --data '{"a":1}', --data @file.json o --data - invia un intero body JSON; i flag ne sovrascrivono i campi.
• cmp help vm firewall add (o --help) mostra i dettagli di qualsiasi comando.

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

Comandi integrati: login, logout, whoami, config, api, completion, version, update, help. Tutto il resto proviene dal documento API.

Flag globali:

Flag	Significato
-o, --output json|table|yaml	Formato. Predefinito table su terminale e json se reindirizzato tramite pipe.
--profile, --api-url	Quale accesso memorizzato e quale sito.
-y, --yes	Ignora la conferma per i comandi distruttivi o a pagamento.
--idempotency-key <k>	Scegli la chiave di un comando a pagamento.
--retry <n>	Su HTTP 429 attende Retry-After e riprova fino a n volte.
--timeout <s>	Secondi di attesa per gli header di risposta (predefinito 60).
--debug	Mostra lo scambio HTTP su stderr, con le chiavi mascherate.

I comandi che addebitano il portafoglio o eliminano dati richiedono una conferma e, se a pagamento, inviano un codice generato automaticamente Idempotency-Key (stampato su stderr, in modo da poter riprovare in sicurezza con --idempotency-key). Senza un terminale vengono rifiutati a meno che non venga fornito --yes.

Codici di uscita

Codice	Significato
0	Successo
1	Altro errore (rete, HTTP 4xx/5xx non elencati)
2	Errore di utilizzo
3	Non autorizzato (401/403)
4	Non trovato (404)
5	Limite di richieste superato (429)
6	Conferma richiesta o rifiutata
130	Interrotto

Profili e ambiente

cmp config elenca i profili; cmp config use <name> effettua il passaggio; i clienti di un rivenditore usano il proprio dominio: cmp login --api-url https://shop.example.net --profile shop. Precedenza: flag, ambiente, file di configurazione. Variabili: 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'

Completamento della shell: cmp completion bash|zsh|fish|powershell.

Aggiornamento e disinstallazione

cmp version
cmp update --check
cmp update

cmp update scarica latest.json, SHA256SUMS e la firma, verifica la firma con la chiave pubblica incorporata nel binario in esecuzione, verifica l'hash del pacchetto e solo allora si sostituisce. Un downgrade richiede --force. Quando aggiorni NexCMP, il pannello fornisce la versione della CLI inclusa nella nuova versione.

Per disinstallare, elimina il binario cmp e la directory di configurazione (cmp config path la mostra). Revoca la chiave in API keys se la macchina viene smarrita.

Verifica

1. cmp version stampa la versione e la versione del documento API.
2. cmp login, approva nel browser, quindi cmp whoami mostra il profilo e l'URL del tuo pannello.
3. cmp vm list restituisce le tue VM; cmp vm list -o json | jq . mostra il JSON grezzo.

Limiti e note

• L'elenco dei comandi dipende dalla tua build: i pacchetti vengono generati dal documento OpenAPI della tua installazione al momento della compilazione della release, quindi un prodotto disabilitato nella tua release non ha alcun comando. Usa cmp api per un percorso che la CLI non riconosce.
• La CLI è distribuita sotto licenza MIT.
• Ciascun pacchetto è firmato con una chiave ed25519; la chiave di firma è fissata all'interno del programma di installazione e del binario, non recuperata al momento dell'aggiornamento.
• Le chiavi sono limitate per chiave e per account (vedi REST API).

Troubleshooting

Sintomo	Causa	Soluzione
curl .../cli/install.sh restituisce 404	La release sul server non ha alcuna cartella CLI, oppure l'host non è incluso nella licenza	Controlla https://<domain>/cli/latest.json e il dominio; aggiorna NexCMP.
"impossibile verificare la firma"	ssh-keygen mancante o troppo vecchio	Installa OpenSSH 8.0+ oppure imposta CMP_REQUIRE_SIGNATURE=0 solo se accetti il rischio.
cmp login indica che il codice è scaduto	Sono trascorsi 10 minuti	Esegui di nuovo cmp login.
Codice di uscita 3	La chiave non ha un ambito, è scaduta o è stata revocata	cmp whoami; crea o riapprova con più ambiti.
Codice di uscita 6 in uno script	Comando a pagamento o distruttivo senza un terminale	Aggiungi --yes (e il tuo --idempotency-key).
"rifiuta di inviare una chiave su http"	URL API HTTP in chiaro	Usa https:// oppure CMP_ALLOW_HTTP=1 solo per un ambiente di test.
Il browser apre il sito sbagliato	--api-url non impostato per un rivenditore	cmp login --api-url https://<reseller-domain>.