# Servidor xamiSDK — Comandos (CLI)

Todos los comandos del CLI `xamisdk`. Ejecuta `xamisdk <comando> --help` para ver la
ayuda de cada uno.

## Pareo y estado

### `init`
Ceremonia de pareo con Xami (única). Establece el canal seguro.

```
xamisdk init --sdk-key xsdk_live_... --secret ...
```

| Opción | Descripción |
|---|---|
| `--sdk-key` | Matrícula (`xsdk_live_...`). |
| `--secret` | Secret de la matrícula. |
| `--receive-url` | URL donde Xami empujará los resultados (modo push). Por defecto `http://127.0.0.1:8300/receive`. En modo pull no se usa. |
| `--endpoint` | Endpoint de Xami (por defecto `https://api.xami.run`). |
| `--force` | Rehace la ceremonia aunque ya esté pareado. |

### `status`
Muestra el estado del pareo: matrícula, tenant, endpoint, versión y estado de las llaves.

```
xamisdk status
```

## Caché local

### `cache:show`
Resumen de la caché local (credenciales y diseños sincronizados).

```
xamisdk cache:show
```

### `credentials:list`
Lista las credenciales disponibles en la caché.

```
xamisdk credentials:list
```

### `designs:list`
Lista los diseños de sello disponibles en la caché.

```
xamisdk designs:list
```

### `designs:show`
Detalle de un diseño concreto.

```
xamisdk designs:show <design_key>
```

## Firma de documentos (PAdES)

### `pades:sign`
Firma un PDF. El documento no sale de tu red.

```
xamisdk pades:sign documento.pdf --credential-key TU_CREDENCIAL --wait
```

| Opción | Descripción |
|---|---|
| `pdf` | Ruta del PDF a firmar (posicional, requerido). |
| `--credential-key` | Credencial a usar (**requerido**). |
| `--design` | `design_key` (si no, se usa el diseño por defecto de la credencial). |
| `--var clave=valor` | Variable del sello. Repetible. |
| `--reason` | Razón de la firma. |
| `--location` | Lugar de la firma. |
| `--signer-name` | Nombre del firmante. |
| `--out` | Ruta de salida del PDF firmado. |
| `--wait` | Espera el resultado y guarda el PDF. |
| `--timeout` | Segundos de espera en modo `--wait` (por defecto 60). |

## Firma blockchain (EVM)

### `blockchain:sign`
Firma el hash (keccak256) de una transacción EVM. El chip actúa como wallet y devuelve
la firma `r`/`s`/`v`; tú ensamblas la transacción con tu web3.

```
xamisdk blockchain:sign <hash> --credential-key TU_CREDENCIAL_EVM --chain-id 648541 --wait
```

| Opción | Descripción |
|---|---|
| `hash` | keccak256 de la tx (64 hex, con o sin `0x`) (posicional, requerido). |
| `--credential-key` | Credencial EVM / wallet (**requerido**). |
| `--chain-id` | Chain id (EIP-155). |
| `--wait` | Espera `r`/`s`/`v`. |
| `--timeout` | Segundos de espera (por defecto 60). |

## Resultados por push

### `callbacks:list`
Lista los resultados de firma recibidos por push.

```
xamisdk callbacks:list
```

### `callbacks:show`
Detalle de un resultado de firma por su id.

```
xamisdk callbacks:show <request_id>
```

## Credenciales de librería (wrapper)

Para que una aplicación externa firme a través del servicio HTTP local, necesita una
credencial de acceso. Estos comandos la gestionan.

### `wrapper:create`
Emite una credencial para una aplicación. Devuelve `wrapper_key` y `wrapper_secret`.

```
xamisdk wrapper:create --name mi-aplicacion
```

| Opción | Descripción |
|---|---|
| `--name` | Nombre de la aplicación (**requerido**). |

### `wrapper:list`
Lista las credenciales de aplicación emitidas.

```
xamisdk wrapper:list
```

### `wrapper:revoke`
Revoca una credencial de aplicación.

```
xamisdk wrapper:revoke <wrapper_key>
```

## Servicio HTTP

### `serve`
Levanta el servicio HTTP local del xamiSDK, para que tus aplicaciones firmen a través de
una librería (XamiLib).

```
xamisdk serve --port 8300
```

Modo **pull** (recomendado para probar desde una PC detrás de NAT): Xami no te empuja los
resultados; el SDK los recoge por polling. Añade `--polling` con el intervalo en
segundos:

```
xamisdk serve --port 8300 --polling 2
```

| Opción | Descripción |
|---|---|
| `--host` | Host de escucha (por defecto `127.0.0.1`). |
| `--port` | Puerto (por defecto `8300`). |
| `--polling` | Intervalo en segundos para recoger resultados de Xami (modo pull). `-1` (por defecto) = inactivo (modo push, Xami empuja al `receive_url`). |