La CLI pluspanel

pluspanel es un único binario estático para Linux, macOS y Windows (amd64 y arm64). Cada operación de la API pública es un comando, con los mismos permisos que el panel. No envía telemetría, ni estadísticas, ni comprobaciones de actualizaciones: solo habla con la dirección del panel que configures.

Instalación

Linux y macOS:

curl -fsSL https://get.pluspanel.net/cli.sh | sh

Windows (PowerShell):

irm https://get.pluspanel.net/cli.ps1 | iex

Los instaladores descargan la última versión desde GitHub (112tech/pluspanel-cli), comprueban siempre su suma SHA-256 y, además, la firma cosign de las sumas cuando cosign está instalado. Nunca llaman a sudo: cli.sh instala en ~/.local/bin (como root: /usr/local/bin) y cli.ps1 en %LOCALAPPDATA%\Programs\pluspanel, que añade al PATH de tu usuario. Puedes elegir el directorio o la versión:

curl -fsSL https://get.pluspanel.net/cli.sh | sh -s -- --prefix /opt/bin --version 0.1.0

¿Prefieres leer el script antes de ejecutarlo? Descárgalo primero:

curl -fsSLO https://get.pluspanel.net/cli.sh
less cli.sh
sh cli.sh

Verifica tú mismo una descarga

Cada versión incluye los archivos pluspanel_<versión>_<os>_<arch>.tar.gz (Windows: .zip), un fichero SHA256SUMS y su firma cosign SHA256SUMS.sig, hecha con la clave de publicación de PlusPanel: cosign.pub.

curl -fsSLO https://pluspanel.net/docs/cli/cosign.pub
cosign verify-blob --key cosign.pub --signature SHA256SUMS.sig --insecure-ignore-tlog=true SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS   # macOS: shasum -a 256 --ignore-missing -c SHA256SUMS

Los dos comandos deben terminar bien antes de usar el binario. La firma se hace sin conexión con la clave de publicación y no se sube a un registro público de transparencia, de ahí --insecure-ignore-tlog=true: la confianza viene de la clave.

Iniciar sesión

pluspanel login --api-url https://panel.example.com

La CLI muestra un código corto y abre la página /device del panel en tu navegador. Inicia sesión allí como siempre (contraseña y segundo factor, o una passkey), comprueba que el código y la solicitud (nombre del dispositivo, dirección IP, hora) son tuyos y apruébala. Al aprobar se te pide confirmar de nuevo tu identidad (contraseña o código del autenticador) si no lo has hecho en los últimos 5 minutos. La CLI recibe entonces una clave de API personal, válida 90 días y revocable en Ajustes → API, y la guarda en un archivo que solo tú puedes leer (0600), en su directorio de configuración. En la página de aprobación puedes hacer que la clave sea solo de lectura.

Sin navegador en esta máquina, añade --no-browser y abre la dirección mostrada en cualquier otro lugar. --client-name cambia el nombre que se muestra en la página de aprobación (por defecto: pluspanel CLI on <hostname>).

pluspanel whoami muestra el usuario, la organización y la clave en uso. pluspanel logout olvida la clave guardada; pluspanel logout --revoke además la revoca en el plano de control.

En CI y en scripts

Usa una clave de API creada para ese trabajo, con los scopes que necesita, desde el almacén de secretos de tu CI:

export PLUSPANEL_API_URL=https://panel.example.com
export PLUSPANEL_API_KEY="$PLUSPANEL_CI_KEY"
pluspanel servers list -o json

O guarda una clave en un perfil: --api-key la lee de la entrada estándar y --api-key-file de un archivo, para que no acabe en el historial del shell:

printf '%s' "$PLUSPANEL_CI_KEY" | pluspanel login --api-url https://panel.example.com --api-key
pluspanel login --api-url https://panel.example.com --api-key-file ~/.pluspanel-key

La CLI comprueba que lo que lee parece una clave de PlusPanel (ppk_…) antes de enviarlo a ningún sitio.

Perfiles

Los perfiles separan varios planos de control, por ejemplo staging y producción:

pluspanel login --profile staging --api-url https://staging.example.com
pluspanel login --profile prod --api-url https://panel.example.com
pluspanel profiles list
pluspanel profiles use prod
pluspanel profiles set prod --default-output json
pluspanel --profile staging servers list
PLUSPANEL_PROFILE=prod pluspanel accounts list
pluspanel profiles delete staging

Sin --profile se usa el perfil actual (el primero en el que iniciaste sesión, o el elegido con profiles use). Los archivos están en el directorio de configuración del usuario: ~/.config/pluspanel/ (o $XDG_CONFIG_HOME/pluspanel) en Linux, ~/Library/Application Support/pluspanel en macOS, %AppData%\pluspanel en Windows; PLUSPANEL_CONFIG_DIR lo sustituye. config.yaml contiene los perfiles (sin secretos) y credentials.yaml las claves, con modo 0600: la CLI se niega a leerlo si otros usuarios pueden hacerlo.

Variable	Efecto
`PLUSPANEL_PROFILE`	perfil que se usa
`PLUSPANEL_API_URL`	dirección de la API (sustituye la del perfil)
`PLUSPANEL_API_KEY`	clave de API (sustituye la guardada)
`PLUSPANEL_CONFIG_DIR`	directorio de configuración
`NO_COLOR`	sin cabeceras en negrita en las tablas (y `--no-color`)

Formatos de salida

-o table (por defecto, para personas), -o json y -o yaml (para programas). La salida JSON es la respuesta de la API sin cambios, así que se puede pasar a jq:

# Every server's name and status
pluspanel servers list --all -o json | jq -r '.items[] | "\(.name)\t\(.status)"'

# Accounts as CSV
pluspanel accounts list --all -o json | jq -r '.items[] | [.id, .name] | @csv'

--all sigue next_cursor por todas las páginas; sin él, una lista muestra una página y el cursor siguiente (--cursor la obtiene). --verbose muestra en la salida de errores cada petición, su estado, el id de la petición y el límite restante (nunca la clave). Los errores se ven así: Error: <detail> (code <code>, request <id>). Códigos de salida: 0 éxito, 1 error de uso o de la API, 2 autenticación (401/403, sin sesión), 3 no encontrado, 4 conflicto, precondición fallida o límite de peticiones (409/412/429), 5 no se pudo contactar con la API.

Ejemplos

# Servers and accounts
pluspanel servers list
pluspanel servers get 6f1c2d3e-…
pluspanel accounts list

# Launch a WordPress site in an account (retries are safe with --idempotency-key)
pluspanel sites launch 5a5a5a5a-… \
  --primary-domain shop.example.com --title Shop --admin-email owner@example.com \
  --idempotency-key "$(uuidgen)"

# Full request bodies from a file or standard input
pluspanel sites launch 5a5a5a5a-… --data-file site.json
pluspanel dns create-record 7c7c7c7c-… --data '{"name":"www","type":"CNAME","content":"example.com."}'

# Optimistic concurrency: send back the ETag of the GET you read (412 if the object changed
# meanwhile; see Conventions → ETags for reading it with curl)
pluspanel security put-site 6b6b6b6b-… --data-file security.json --if-match "$etag"

# API keys and webhooks
pluspanel api-keys create --name ci --scopes 'servers:read,sites:write' -o json
pluspanel api-keys list
pluspanel webhooks create --url https://hooks.example.com/pluspanel --events 'site.*,backup.failed'
pluspanel webhooks list-deliveries 9d9d9d9d-… --state dead

# Any operation by path, like curl with your credentials
pluspanel api GET /php-versions
pluspanel api GET '/audit?limit=5'

Los comandos se agrupan por recurso (pluspanel --help lista los grupos, pluspanel <grupo> --help sus comandos). Los parámetros de la ruta son argumentos posicionales, en el orden de la ruta; los parámetros de consulta y los miembros de primer nivel del cuerpo son flags (listas separadas por comas); cada POST acepta --idempotency-key y cada PUT (y cada PATCH cuya ruta tiene GET) --if-match. El --help de cada comando muestra su descripción, sus flags y la ruta HTTP, generados a partir de la referencia de la API.

Autocompletado en el shell

pluspanel completion bash > ~/.local/share/bash-completion/completions/pluspanel
pluspanel completion zsh > "${fpath[1]}/_pluspanel"
pluspanel completion fish > ~/.config/fish/completions/pluspanel.fish
pluspanel completion powershell | Out-String | Invoke-Expression