Herramienta de línea de comandos cmp

Ubicación en el portal: los comandos de instalación están en la referencia de la API (https://<your-domain>/apidoc, sección Command-line interface). Aprobación de inicio de sesión: https://<your-domain>/link. Dispositivos conectados: API keys (/api-keys) › Connected apps & devices.

Qué hace

cmp es un pequeño programa de línea de comandos para sus clientes (y para usted) que convierte cada operación de la API en un comando: cmp vm list, cmp vm start <id>, cmp billing invoice list. Se compila a partir del documento OpenAPI de su propia instalación en el momento del lanzamiento, por lo que los comandos coinciden con las funciones que tenga habilitadas. Es un único binario estático para Linux, macOS y Windows (amd64 y arm64) sin nada más que instalar.

Requisitos

Elemento	Requisito
Servidor	Nada adicional. Los paquetes de distribución están dentro de la versión de NexCMP y el panel los sirve en https://<your-domain>/cli/.
Máquina del cliente	Linux, macOS o Windows (PowerShell 5.1+). ssh-keygen (OpenSSH 8.0+) solo es necesario para verificar la firma.
Credenciales	Un inicio de sesión en el navegador con un código de un solo uso o una API key.
Red	HTTPS hacia su panel. La CLI rechaza enviar una clave a través de http:// sin cifrar, excepto a localhost.

Preparar la infraestructura

Nada. El panel sirve estos archivos desde /cli/ (no se requiere compilación ni subida):

Archivo	Propósito
install.sh, install.ps1	Instaladores para Linux/macOS y Windows; contienen la dirección de su panel.
latest.json	Versión actual, lista de archivos, tamaños, sha256.
v<version>/cmp_<version>_<os>_<arch>.tar.gz o .zip	Los programas: linux amd64/arm64, darwin amd64/arm64/universal, windows amd64/arm64.
v<version>/SHA256SUMS, SHA256SUMS.sig	Sumas de verificación y su firma ed25519.
cmp-cli.pub	La clave pública de la versión.

Instalación (cliente)

macOS y Linux:

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

Windows PowerShell:

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

El instalador selecciona el paquete para el SO y la CPU, descarga SHA256SUMS y su firma, verifica la firma con la clave incrustada en el script, comprueba el hash del paquete e instala cmp en /usr/local/bin (como root) o en ~/.local/bin; en Windows en %LOCALAPPDATA%\cmp\bin (añadido al PATH del usuario). Si alguna comprobación falla, no se instala nada.

Variable	Significado
CMP_VERSION	Instalar esta versión en lugar de la más reciente.
CMP_INSTALL_DIR	Carpeta de instalación.
CMP_REQUIRE_SIGNATURE	1 = abortar cuando no se pueda verificar la firma.
CMP_BASE_URL	Base de descarga (para mirrors).

Descarga y verificación manual:

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

Iniciar sesión

cmp login

1. La CLI muestra un código de un solo uso y un enlace (https://cloud.example.com/link?code=WDJB-MJHT), abre el navegador y espera.
2. En el navegador, inicie sesión en el portal, compruebe el nombre del cliente, el dispositivo, la IP y el país, marque los permisos (scopes) y elija la duración de la clave (por defecto 90 días). Los permisos que conllevan costes o eliminan datos aparecen desmarcados inicialmente. Haga clic en approve.
3. La CLI recibe su propia clave, independiente de las claves creadas manualmente por el cliente, y la guarda en ~/.config/cmp/config.json (modo 0600; %APPDATA%\cmp en Windows). Aparece en API keys › Connected apps & devices y se puede revocar allí.

El código caduca a los 10 minutos. La aprobación requiere una sesión real iniciada en el portal con un correo electrónico verificado; no otra clave ni una sesión suplantada.

Flags útiles: --scopes vm:read,billing:read, --name "build server", --no-browser, --profile, --api-url.

Para CI o servidores sin navegador, use una clave del 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]

• Los parámetros de ruta son argumentos posicionales; los parámetros de consulta y los campos del cuerpo se convierten en flags en kebab-case (--start-port 443).
• --data '{"a":1}', --data @file.json o --data - envía un cuerpo JSON completo; los flags anulan sus campos.
• cmp help vm firewall add (o --help) muestra los detalles de cualquier 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 integrados: login, logout, whoami, config, api, completion, version, update, help. Todo lo demás proviene del documento de la API.

Flags globales:

Flag	Significado
-o, --output json|table|yaml	Formato. Por defecto table en una terminal y json cuando se canaliza.
--profile, --api-url	Qué inicio de sesión guardado y qué sitio.
-y, --yes	Omitir la confirmación para comandos destructivos o de pago.
--idempotency-key <k>	Elegir la clave de un comando de pago.
--retry <n>	En caso de HTTP 429, esperar Retry-After y reintentar hasta n veces.
--timeout <s>	Segundos de espera para los encabezados de respuesta (por defecto 60).
--debug	Mostrar el intercambio HTTP en stderr, con las claves enmascaradas.

Los comandos que cargan el monedero o eliminan datos solicitan confirmación y, si son de pago, envían un Idempotency-Key generado automáticamente (impreso en stderr, para que pueda reintentar de forma segura con --idempotency-key). Sin un terminal se rechazan a menos que se indique --yes.

Códigos de salida

Código	Significado
0	Éxito
1	Otro error (red, HTTP 4xx/5xx no listados)
2	Error de uso
3	No autorizado (401/403)
4	No encontrado (404)
5	Límite de solicitudes superado (429)
6	Confirmación requerida o rechazada
130	Interrumpido

Perfiles y entorno

cmp config lista los perfiles; cmp config use <name> cambia de perfil; los clientes de un revendedor utilizan su propio dominio: cmp login --api-url https://shop.example.net --profile shop. Prioridad: flag, entorno, archivo de configuración. Variables: 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'

Autocompletado de shell: cmp completion bash|zsh|fish|powershell.

Actualización y desinstalación

cmp version
cmp update --check
cmp update

cmp update descarga latest.json, SHA256SUMS y la firma, verifica la firma con la clave pública integrada en el binario en ejecución, comprueba el hash del paquete y solo entonces se reemplaza a sí mismo. Una degradación requiere --force. Al actualizar NexCMP, el panel sirve la versión de la CLI incluida con la nueva versión.

Para desinstalar, elimine el binario cmp y el directorio de configuración (cmp config path lo muestra). Revoque la clave en API keys si la máquina se pierde.

Verificación

1. cmp version imprime la versión y la versión del documento de la API.
2. cmp login, apruebe en el navegador y luego cmp whoami muestra el perfil y la URL de su panel.
3. cmp vm list devuelve sus VM; cmp vm list -o json | jq . muestra el JSON sin procesar.

Límites y notas

• La lista de comandos depende de su compilación: los paquetes se generan a partir del documento OpenAPI de su instalación al compilar la versión, por lo que un producto desactivado en su versión no tendrá ningún comando. Utilice cmp api para una ruta que la CLI no conozca.
• La CLI está bajo la licencia MIT.
• Cada paquete está firmado con una clave ed25519; la clave de firma está anclada dentro del instalador y del binario, no se descarga durante la actualización.
• Las claves están limitadas por clave y por cuenta (consulte REST API).

Resolución de problemas

Síntoma	Causa	Solución
curl .../cli/install.sh devuelve 404	La versión en el servidor no tiene carpeta CLI o el host no está en la licencia	Compruebe https://<domain>/cli/latest.json y el dominio; actualice NexCMP.
"no se pudo verificar la firma"	ssh-keygen falta o es demasiado antiguo	Instale OpenSSH 8.0+ o configure CMP_REQUIRE_SIGNATURE=0 solo si acepta el riesgo.
cmp login indica que el código ha caducado	Han pasado 10 minutos	Ejecute cmp login de nuevo.
Código de salida 3	La clave carece de un ámbito, ha caducado o está revocada	cmp whoami; cree o vuelva a aprobar con más ámbitos.
Código de salida 6 en un script	Comando de pago o destructivo sin un terminal	Añada --yes (y su propio --idempotency-key).
"se niega a enviar una clave por http"	URL de la API en http sin cifrar	Utilice https://, o CMP_ALLOW_HTTP=1 solo para un laboratorio.
El navegador abre el sitio incorrecto	--api-url no está configurado para un revendedor	cmp login --api-url https://<reseller-domain>.