---
title: strumento a riga di comando cmp
description: Installa e usa la CLI cmp del tuo pannello: login browser con codice monouso, comandi da API, output, codici di uscita, CI e aggiornamenti firmati.
url: https://nexcmp.com/it/docs/developers/cmp-cli/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Strumento a riga di comando `cmp` {#cmp-command-line-tool}

> **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 {#what-it-does}

`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 {#requirements}

| 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](https://nexcmp.com/it/docs/developers/api-keys/). |
| Rete | HTTPS verso il pannello. La CLI rifiuta di inviare una chiave su connessioni non protette `http://`, eccetto verso `localhost`. |

## Prepara l'infrastruttura {#prepare-the-infrastructure}

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) {#install-customer}

macOS e Linux:

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

Windows PowerShell:

```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:

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

![Sezione di riferimento API con il comando di installazione di cmp per macOS e Linux](https://nexcmp.com/it/docs/images/developers/cmp-cli-01-install.webp)

## Accesso {#log-in}

```bash
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:

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

## Uso dei comandi {#using-commands}

```text
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.

```bash
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 {#exit-codes}

| 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 {#profiles-and-environment}

`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:

```yaml
- 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 {#update-and-uninstall}

```bash
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 {#verify}

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 {#limits-notes}

- 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](https://nexcmp.com/it/docs/developers/api/#rate-limits)).

## Troubleshooting {#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>`. |