--- title: ferramenta de linha de comando cmp description: Instale e use o cmp CLI do seu painel: login no navegador com código único, comandos via API, códigos de saída, uso em CI e atualizações assinadas. url: https://nexcmp.com/pt/docs/developers/cmp-cli/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # ferramenta de linha de comando `cmp` {#cmp-command-line-tool} > **Onde no portal:** os comandos de instalação estão na referência da API (`https:///apidoc`, seção Command-line interface). Aprovação de um login: `https:///link`. Dispositivos conectados: API keys (`/api-keys`) › Connected apps & devices. ## O que faz {#what-it-does} `cmp` é um pequeno programa de linha de comando para seus clientes (e para você) que transforma **cada operação de API em um comando**: `cmp vm list`, `cmp vm start `, `cmp billing invoice list`. Ele é compilado a partir do documento OpenAPI da **sua** instalação no momento do lançamento, portanto, os comandos correspondem aos recursos que você ativou. É um único binário estático para Linux, macOS e Windows (amd64 e arm64) sem necessidade de instalação adicional. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Servidor | Nada extra. Os pacotes de lançamento estão dentro da versão do NexCMP e são servidos pelo painel em `https:///cli/`. | | Máquina do cliente | Linux, macOS ou Windows (PowerShell 5.1+). `ssh-keygen` (OpenSSH 8.0+) é necessário apenas para verificar a assinatura. | | Credenciais | Um login de navegador com um código de uso único ou uma [API key](https://nexcmp.com/pt/docs/developers/api-keys/). | | Rede | HTTPS para o seu painel. A CLI recusa o envio de uma chave por `http://` puro, exceto para `localhost`. | ## Preparar a infraestrutura {#prepare-the-infrastructure} Nada. O painel serve esses arquivos de `/cli/` (sem necessidade de build ou upload): | Arquivo | Finalidade | |---|---| | `install.sh`, `install.ps1` | Instaladores para Linux/macOS e Windows; eles contêm o endereço do seu painel. | | `latest.json` | Versão atual, lista de arquivos, tamanhos, sha256. | | `v/cmp___.tar.gz` ou `.zip` | Os programas: linux amd64/arm64, darwin amd64/arm64/universal, windows amd64/arm64. | | `v/SHA256SUMS`, `SHA256SUMS.sig` | Somas de verificação (checksums) e sua assinatura ed25519. | | `cmp-cli.pub` | A chave pública de lançamento. | ## Instalação (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 ``` O instalador escolhe o pacote para o SO e CPU, baixa `SHA256SUMS` e sua assinatura, verifica a assinatura com a chave embutida no script, verifica o hash do pacote e instala `cmp` em `/usr/local/bin` (como root) ou `~/.local/bin`; no Windows, em `%LOCALAPPDATA%\cmp\bin` (adicionado ao `PATH` do usuário). Se uma verificação falhar, nada é instalado. | Variável | Significado | |---|---| | `CMP_VERSION` | Instalar esta versão em vez da mais recente. | | `CMP_INSTALL_DIR` | Pasta de instalação. | | `CMP_REQUIRE_SIGNATURE` | `1` = abortar quando a assinatura não puder ser verificada. | | `CMP_BASE_URL` | Base de download (para mirrors). | Download manual e verificação: ```bash curl -fsSLO https://cloud.example.com/cli/latest.json sha256sum --check --ignore-missing SHA256SUMS ``` ![Seção de referência da API com o comando cmp install para macOS e Linux](https://nexcmp.com/pt/docs/images/developers/cmp-cli-01-install.webp) ## Fazer login {#log-in} ```bash cmp login ``` 1. A CLI exibe um **código** de uso único e um link (`https://cloud.example.com/link?code=WDJB-MJHT`), abre o navegador e aguarda. 2. No navegador, faça login no portal, verifique o nome do cliente, dispositivo, IP e país, marque as permissões (scopes) e escolha o tempo de vida da chave (padrão de 90 dias). Permissões que geram custos ou excluem dados vêm desmarcadas por padrão. Clique em aprovar. 3. A CLI recebe **sua própria chave**, separada das chaves criadas manualmente pelo cliente, e a armazena em `~/.config/cmp/config.json` (modo `0600`; `%APPDATA%\cmp` no Windows). Ela aparece em **API keys › Connected apps & devices** e pode ser revogada lá. O código expira após 10 minutos. A aprovação exige uma sessão real autenticada no portal com um e-mail verificado — não outra chave nem uma sessão impersonada. Flags úteis: `--scopes vm:read,billing:read`, `--name "build server"`, `--no-browser`, `--profile`, `--api-url`. Para CI ou servidores sem navegador, use uma chave do portal: ```bash printf %s "$KEY" | cmp login --with-token export CMP_TOKEN=vk_XXXX # nothing is written to disk cmp whoami ``` ## Uso de comandos {#using-commands} ```text cmp [subgroup] [ ...] [flags] ``` - Parâmetros de caminho são argumentos posicionais; parâmetros de query e campos de corpo tornam-se flags em kebab-case (`--start-port 443`). - `--data '{"a":1}'`, `--data @file.json` ou `--data -` envia um corpo JSON completo; as flags sobrescrevem seus campos. - `cmp help vm firewall add` (ou `--help`) mostra os detalhes de qualquer 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 ``` Comandos nativos: `login`, `logout`, `whoami`, `config`, `api`, `completion`, `version`, `update`, `help`. Tudo o mais vem do documento da API. Flags globais: | Flag | Significado | |---|---| | `-o, --output json\|table\|yaml` | Formato. Padrão `table` em um terminal e `json` quando redirecionado. | | `--profile`, `--api-url` | Qual login salvo e qual site. | | `-y, --yes` | Ignorar confirmação para comandos destrutivos ou pagos. | | `--idempotency-key ` | Escolher a chave para um comando pago. | | `--retry ` | Em HTTP 429, aguardar por `Retry-After` e tentar novamente até n vezes. | | `--timeout ` | Segundos para aguardar os headers de resposta (padrão 60). | | `--debug` | Mostrar a troca HTTP em stderr, com chaves mascaradas. | Comandos que **cobram da carteira ou excluem dados** pedem confirmação e, se pagos, enviam um `Idempotency-Key` gerado automaticamente (impresso em stderr, para que você possa tentar novamente com segurança usando `--idempotency-key`). Sem um terminal, eles recusam a execução, a menos que `--yes` seja fornecido. ### Códigos de saída {#exit-codes} | Código | Significado | |---|---| | 0 | Sucesso | | 1 | Outro erro (rede, HTTP 4xx/5xx não listado) | | 2 | Erro de uso | | 3 | Não autorizado (401/403) | | 4 | Não encontrado (404) | | 5 | Limite de requisições excedido (429) | | 6 | Confirmação necessária ou recusada | | 130 | Interrompido | ### Perfis e ambiente {#profiles-and-environment} `cmp config` lista os perfis; `cmp config use ` alterna entre eles; os clientes de um revendedor usam o próprio domínio: `cmp login --api-url https://shop.example.net --profile shop`. Precedência: flag, ambiente, arquivo de configuração. Variáveis: `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' ``` Conclusão do shell: `cmp completion bash|zsh|fish|powershell`. ## Atualização e desinstalação {#update-and-uninstall} ```bash cmp version cmp update --check cmp update ``` `cmp update` baixa `latest.json`, `SHA256SUMS` e a assinatura, verifica a assinatura com a chave pública **embutida no binário em execução**, verifica o hash do pacote e só então se substitui. Um downgrade requer `--force`. Quando você atualiza o NexCMP, o painel disponibiliza a versão da CLI que acompanha a nova versão. Para desinstalar, exclua o binário `cmp` e o diretório de configuração (`cmp config path` mostra o caminho). Revogue a chave em **API keys** caso a máquina seja perdida. ## Verificar {#verify} 1. `cmp version` exibe a versão e a versão do documento da API. 2. `cmp login`, aprove no navegador e, em seguida, `cmp whoami` exibe o perfil e a URL do seu painel. 3. `cmp vm list` retorna suas VMs; `cmp vm list -o json | jq .` exibe o JSON bruto. ## Limites e notas {#limits-notes} - A lista de comandos depende da sua compilação: os pacotes são gerados a partir do documento OpenAPI da sua instalação no momento da criação da release, portanto, um produto desativado na sua versão não possui comando correspondente. Use `cmp api` para um caminho que a CLI desconhece. - A CLI está sob a licença MIT. - Cada pacote é assinado com uma chave ed25519; a chave de assinatura está fixada (pinned) no instalador e no binário, não sendo buscada no momento da atualização. - As chaves possuem limites por chave e por conta (consulte [REST API](https://nexcmp.com/pt/docs/developers/api/#rate-limits)). ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | `curl .../cli/install.sh` retorna 404 | A release no servidor não possui pasta CLI ou o host não está na licença | Verifique `https:///cli/latest.json` e o domínio; atualize o NexCMP. | | "assinatura não pôde ser verificada" | `ssh-keygen` ausente ou desatualizado | Instale o OpenSSH 8.0+ ou defina `CMP_REQUIRE_SIGNATURE=0` apenas se aceitar o risco. | | `cmp login` indica que o código expirou | 10 minutos se passaram | Execute `cmp login` novamente. | | Código de saída 3 | A chave não possui um escopo, expirou ou foi revogada | `cmp whoami`; crie ou re-aprove com mais escopos. | | Código de saída 6 em um script | Comando pago ou destrutivo sem um terminal | Adicione `--yes` (e o seu próprio `--idempotency-key`). | | "recusa-se a enviar uma chave por http" | URL de API HTTP simples (sem TLS) | Use `https://` ou `CMP_ALLOW_HTTP=1` apenas para laboratório. | | O navegador abre o site incorreto | `--api-url` não definido para um revendedor | `cmp login --api-url https://`. |