docs(shipote): README + 4 docs en docs/ (ARCHITECTURE, CLI, RECIPES, DEVELOPMENT)
- README.md en crates/modules/shipote/ como entry point. - docs/ARCHITECTURE.md — 11 crates, capas, decisiones (O_CLOEXEC, dirty AtomicBool, pipeline restart entero, etc.) + snapshot versioning. - docs/CLI.md — referencia comando por comando, flags, env vars. - docs/RECIPES.md — specs TOML para workspaces y pipelines típicos. - docs/DEVELOPMENT.md — compilar, correr daemon/shell/CLI, tests, smoke E2E manual, debugging FDs. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
sergio
@@ -0,0 +1,134 @@
|
||||
# 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"
|
||||
```
|
||||
Reference in New Issue
Block a user