lobster

name	lobster
description	Run deterministic typed pipelines, workflow files, and approval-gated automations via the Lobster CLI. Use for multi-step automations that need safety (approval gates), statefulness (cursors/checkpoints), and token efficiency (one call vs many LLM re-plans). Triggers on workflow automation, pipeline, deterministic execution, approval gate, email triage, PR monitor.

Lobster — Workflow Shell

Typed, local-first pipeline engine. Deterministic execution, approval gates, persistent state. Saves tokens by replacing multi-step LLM re-planning with one-shot pipeline calls.

CLI

lobster '<pipeline>'                    # inline pipeline
lobster run path/to/workflow.lobster    # YAML workflow file
lobster run --file wf.lobster --args-json '{"key":"val"}'
lobster resume --token <token> --approve yes|no
lobster doctor                          # health check
lobster help <command>                  # per-command help

Pipeline Commands

Data flow

Command	Purpose	Example
exec	Run OS command	exec --json --shell 'echo [1,2]'
where	Filter	where 'status=OPEN'
pick	Project fields	pick 'title,author,url'
head	First N items	head --n 5
sort	Stable sort	sort --key updatedAt --desc
groupBy	Group by key	groupBy --key category
dedupe	Remove dupes	dedupe --key id
map	Transform	map --wrap items / map status=done
template	Render text	template --text '{{title}} by {{author}}'

Output

Command	Purpose
json	JSON output
table	Table output

Control flow

Command	Purpose
approve	Halt for approval (--emit for non-TTY/tool mode)
state.get	Read persistent state
state.set	Write persistent state
diff.last	Compare to last snapshot

Integrations

Command	Purpose
clawd.invoke	Call OpenClaw tool endpoint
gog.gmail.search	Fetch Gmail threads
gog.gmail.send	Send Gmail
email.triage	Categorize + draft replies
llm_task.invoke	Call LLM with typed payloads
workflows.run	Run named workflow
workflows.list	List available workflows

Pipe syntax

Commands are piped with |. Data flows as typed JSON arrays (not text).

lobster "exec --json --shell 'gh pr list --json number,title,state' | where 'state=OPEN' | pick 'number,title' | head --n 5 | table"

Workflow files (.lobster)

YAML files with steps, env vars, conditions, and approval gates:

name: deploy-check
steps:
  - id: tests
    command: exec --json --shell 'pnpm test --json'
  - id: approve
    command: approve --prompt "Tests passed. Deploy to staging?"
    approval: required
  - id: deploy
    command: exec --shell 'pnpm deploy:staging'
    condition: $approve.approved

Run: lobster run deploy-check.lobster

Steps can reference prior outputs: stdin: $tests.stdout

Tool mode (for OpenClaw integration)

lobster run --mode tool '<pipeline>'

Returns a JSON envelope: { ok, status, output, requiresApproval }

When status: "needs_approval", call lobster resume --token <token> --approve yes to continue.

Built-in recipes

GitHub PR Monitor

lobster "workflows.run --name github.pr.monitor --args-json '{\"repo\":\"owner/repo\",\"pr\":123}'"

Tracks PR state changes with diff detection.

State persistence

state.set / state.get persist JSON values across runs (e.g., last-processed cursor). diff.last compares current data to a stored snapshot and emits only changes.

Key principles

• One call — replace 10+ LLM tool calls with one pipeline
• Approval gates — hard stops, not prompt hints. Pipeline cannot continue without explicit resume.
• Stateful — cursors/checkpoints survive across runs
• No auth surface — Lobster never owns tokens; uses env vars or OpenClaw's existing auth