---
title: Conexión con el panel
description: Conecta Plak CLI a tu cuenta con aprobación en el panel o clave manual.
sidebar:
  label: Conexión
  order: 1
---

`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.

```bash
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

1. **Pide el pairing**

    ```bash
    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.

2. **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.

3. **Verifica la conexión**

    ```bash
    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:

```bash
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

```bash
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):

```bash
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](/cli/panel) o [vinculación y migraciones](/cli/vincular).