Conexión con el panel

Conecta Plak CLI a tu cuenta con aprobación en el panel o clave manual.

plak connect vincula esta máquina a tu cuenta del panel con un device flow estilo Botmail: la CLI pide un pairing, muestra y abre el enlace de aprobación, apruebas con 1 clic en el panel y la CLI obtiene una API key personal sin copiar secretos a mano.

plak connect                          # device flow (abre el navegador si puede)
plak connect --no-open                # imprime el enlace sin abrir navegador
plak connect --manual --token-stdin   # fallback headless/WSL/automatización
plak connect status                   # panel, cuenta y validez del token
plak disconnect                       # olvida la credencial local

Flujo recomendado

Pide el pairing

plak connect

La CLI solicita POST /api/v1/cli/pair, muestra el approve_url (y el código de pairing) e intenta abrirlo en el navegador según la plataforma.

Aprueba en el panel

Inicia sesión si hace falta y aprueba con 1 clic. El mismo token pendiente se convierte en tu API key personal.

En máquinas sin navegador, WSL o salidas no interactivas, la CLI imprime el enlace para aprobarlo manualmente en otro dispositivo.

Verifica la conexión

plak connect status
plak connect status --json

--json nunca incluye el secreto. Si el token es inválido, está revocado o caducado, o la cuenta está bloqueada, el estado lo indica y apunta a plak connect para reconectar.

Opciones del device flow: --panel URL para un origen explícito, --dev para desarrollo, --wait SECS (máximo de espera, por defecto 900) y --poll SECS (intervalo, por defecto 10). Un pairing cancelado, rechazado o expirado no deja conexión a medias ni sobrescribe una conexión válida existente.

Fallback manual

Para entornos sin navegador, headless, WSL y automatizaciones:

echo "$KEY" | plak connect --manual --token-stdin

La clave se genera en el panel (Perfil > API Keys), se pega con entrada oculta y la CLI la valida con GET /api/v1/user antes de guardarla. Pasar el secreto como argumento está prohibido (--token se rechaza); para automatizar usa siempre --token-stdin. Una validación fallida o una cancelación no sobrescribe una conexión válida existente.

Dónde vive la credencial

${PLAK_HOME:-$HOME/.plak}/connection.json: directorio 700, archivo 600, escritura atómica. Contiene panel_url, el token y la identidad mínima (id, name, email).

Nunca se carga con source, nunca sale en logs, ni en --json, ni en el historial.
La credencial queda asociada a la URL del panel: cambiar de panel u origen exige una conexión nueva. El token guardado jamás se envía a otro origen.
Resolución del panel: --panel URL, --dev ($PLAK_PANEL_DEV_URL, por defecto http://127.0.0.1:8000), variable PLAK_PANEL_URL u origen por defecto (https://panel.plak.work). Para el panel de producción (https://cloud.plak.io), pasa --panel https://cloud.plak.io al conectar.

Desconectar no es revocar

plak disconnect
plak disconnect --yes   # no interactivo

plak disconnect solo borra la credencial local. La clave sigue viva en el servidor hasta revocarla en el panel (Perfil > API Keys > Revoke). Revocar ahí no afecta a otras conexiones, y las claves SSH instaladas por separado tienen su propio ciclo de vida.

Desarrollo tras Cloudflare Access

La sesión del navegador no se comparte con este cliente HTTP. Si el panel de desarrollo responde con página o redirección de Access en lugar de JSON, la CLI lo detecta y no lo trata como conexión válida. Proporciona un token de servicio de forma explícita (distinto de la API key de Plak):

export PLAK_CF_ACCESS_TOKEN='<valor>'
plak connect --panel <url-dev>

Se envía como CF-Access-Token y es diferente de la API key de Plak.

Decisión `/connect`

Este CLI no tiene intérprete conversacional: no existe ningún comando /connect. Cualquier adaptador externo debe invocar plak connect y nunca capturar ni reenviar el secreto a una conversación.

Dependencias y errores

curl + python3 (parser JSON real). Sin -L en la API: el Bearer nunca se reenvía a otro origen por redirecciones. 429 respeta Retry-After; el HTML se detecta y se informa en lugar de parsearse.

Síntoma	Qué hacer
`Token invalid...`	Ejecuta `plak connect` de nuevo; la conexión anterior intacta no se usa
`Account blocked`	Contacta soporte; no reintentes con la misma clave
`Panel unreachable`	Revisa red y `plak connect status`; no es un problema de clave
`Pairing expired/rejected`	Repite `plak connect`; no queda estado a medias

Cuando la conexión funciona, continúa con sitios y servidores del panel o vinculación y migraciones.