ferramenta de linha de comando cmp

Onde no portal: os comandos de instalação estão na referência da API (https://<your-domain>/apidoc, seção Command-line interface). Aprovação de um login: https://<your-domain>/link. Dispositivos conectados: API keys (/api-keys) › Connected apps & devices.

O que faz

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 <id>, 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

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://<your-domain>/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.
Rede	HTTPS para o seu painel. A CLI recusa o envio de uma chave por http:// puro, exceto para localhost.

Preparar a infraestrutura

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<version>/cmp_<version>_<os>_<arch>.tar.gz ou .zip	Os programas: linux amd64/arm64, darwin amd64/arm64/universal, windows amd64/arm64.
v<version>/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)

macOS e Linux:

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

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

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

Fazer login

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:

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

Uso de comandos

cmp <group> [subgroup] <action> [<id> ...] [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.

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 <k>	Escolher a chave para um comando pago.
--retry <n>	Em HTTP 429, aguardar por Retry-After e tentar novamente até n vezes.
--timeout <s>	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

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

cmp config lista os perfis; cmp config use <name> 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:

- 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

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

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

• 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).

Resolução de problemas

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://<domain>/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://<reseller-domain>.