# Referencia CLI — `shipote`

El binario `shipote` (compilado por `cargo build -p shipote-cli`) se conecta al daemon vía Unix socket. Por default usa `$XDG_RUNTIME_DIR/shipote.sock`; override con `--socket <path>`.

```sh
shipote [--socket PATH] <comando> [...]
```

## Comandos globales

### `shipote ping`
Health-check rápido. Imprime `pong` si el daemon responde.

### `shipote health`
Health endpoint estructurado.
```
version:           0.1.0
uptime:            11411 ms
alive_workspaces:  1
alive_commands:    1
alive_pipelines:   0
active_flows:      0
dirty:             true
```

### `shipote caps`
Capacidades runtime detectadas: kernel version, `user_ns` status, `cgroup_v2`, `cgroup_delegated`, `cap_sys_admin`.

### `shipote discern <path>`
Discierne ad-hoc un archivo (no requiere workspace). Imprime `ty`, `confidence`, `mime`, `lens`.

## Workspaces

### `shipote workspace create <spec.toml|.json>`
Crea workspace desde un spec. Imprime el ULID asignado. Si el cgroup está delegated y el spec declara rlimits, se aplica `memory.max`/`pids.max`.

### `shipote workspace list`
Lista workspaces vivos.

### `shipote workspace stats <id>`
Resource accounting:
```
commands:   1 alive / 1 total
rss:        2.05 MiB
rss_peak:   58.89 MiB
cpu:        0.300 s
cpu_pct:    98.7 % (24.7% total / 4 cores)
source:     proc
uptime:     1002 ms
```

### `shipote workspace quota <id>`
Reporta breaches del `soma.rlimits`. Si `quota_enforce.{mem,nproc}=Kill`, el daemon mata automáticamente al detectar.

### `shipote workspace stop <id> [--grace-ms N]`
Stop graceful. Default `grace_ms=1000`. `0` = SIGKILL inmediato.

## Comandos directos

### `shipote run -w <ws-id> [--restart-on-failure] <exec> -- <argv>...`
One-shot dentro del workspace. Si `--restart-on-failure`, el reaper relanza con backoff exponencial cuando exit != 0.

**Nota**: usar `--` antes de los argv del comando para que clap no los confunda con flags suyos:
```sh
shipote run -w 01... /bin/sh -- -c "echo hola"
```

### `shipote commands <ws-id>`
Lista comandos del workspace (vivos + exited) con pid, status, bytes_log.

### `shipote logs <ws-id> <cmd-id> [--stream {stdout|stderr|both}] [--tail N] [--follow]`
Tail del ring buffer de logs.
- `--stream` default `stdout`. `both` concatena stderr-tras-stdout.
- `--tail N`: últimos N bytes (0 = todo).
- `--follow` (`-f`): poll cada 200ms, imprime suffix nuevo hasta que el comando termine.

## Pipelines

### `shipote pipeline run <spec.toml> [--tap] [--tail] [--var KEY=VAL ...]`
Lanza pipeline.
- `--tap`: crea flow channels (data plane) por cada edge.
- `--tail`: auto-implica `--tap`, suscribe al primer flow socket y vuelca a stdout.
- `--var KEY=VAL` (repetible): sustituye `${KEY}` en el spec antes de lanzar.

### `shipote pipeline stop <pipeline-id> [--grace-ms N]`
Stop selectivo del pipeline (no afecta otros comandos del workspace).

### `shipote pipeline save <name> <spec.toml>`
Persiste el spec bajo `name` (sobrevive restart vía snapshot).

### `shipote pipeline saved-list`
Lista pipelines guardados.

### `shipote pipeline drop <name>`
Elimina un saved pipeline.

### `shipote pipeline run-saved <name> [--tap] [--tail] [--var KEY=VAL ...]`
Ejecuta un pipeline guardado con vars opcionales.

## Flows

### `shipote flow list`
Lista pipelines vivos con sockets activos (uno por edge con `--tap`).

### `shipote flow throughput`
Bytes acumulados + rate por socket.
```
shipote-flow-<ULID>-0.sock  0.1 KiB total  0.07 KiB/s
```

### `shipote flow tail <socket-path>`
Conecta directo al Unix socket y vuelca hasta EOF. Si el splitter tiene replay buffer, lo recibís primero.

### `shipote flow drop <pipeline-id>`
Cierra el data plane de un pipeline (drop de FlowChannels).

## Variables de entorno

- `SHIPOTE_LOG` — filtro `tracing-subscriber` (`info`, `warn`, `audit=info,warn`, ...).
- `SHIPOTE_TRUST_ANYONE=1` — daemon acepta peers con cualquier uid (testing).
- `XDG_RUNTIME_DIR` — dónde se crea el socket admin y los flow sockets.
- `XDG_STATE_HOME` — dónde se guarda el snapshot. Fallback: `$HOME/.local/state/shipote/state.json`.

## Trucos del shell zsh

`shipote run` toma flags propios antes del `--`. Si el comando que ejecutás tiene un argumento que arranca con `-`, usá `--`:

```sh
# Mal (clap intenta parsear `-c` como flag de shipote):
shipote run -w <ws> /bin/sh -c "echo hi"

# Bien:
shipote run -w <ws> /bin/sh -- -c "echo hi"
```