brahman/crates/modules/shipote/docs/CLI.md

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

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:

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á --:

# 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"