Run pipeline (human mode - pretty output)

$LOBSTER ''

Run pipeline (tool mode - JSON envelope for integration)

$LOBSTER run --mode tool ''

Run workflow file

$LOBSTER run path/to/workflow.lobster

Resume after approval

$LOBSTER resume --token "" --approve yes|no

List commands/workflows

$LOBSTER commands.list $LOBSTER workflows.list


## Core Commands

| Command | Purpose |
|---------|---------|
| `exec --json --shell "cmd"` | Run shell, parse stdout as JSON |
| `where 'field=value'` | Filter objects |
| `pick field1,field2` | Project fields |
| `head --n 5` | Take first N items |
| `sort --key field --desc` | Sort items |
| `groupBy --key field` | Group by key |
| `dedupe --key field` | Remove duplicates |
| `map --wrap key` | Transform items |
| `template --text "{{field}}"` | Render templates |
| `approve --prompt "ok?"` | **Halt for approval** |
| `diff.last --key "mykey"` | Compare to last run (stateful) |
| `state.get key` / `state.set key` | Read/write persistent state |
| `json` / `table` | Render output |

## Built-in Workflows

```bash
# Monitor PR for changes (stateful - remembers last state)
$LOBSTER "workflows.run --name github.pr.monitor --args-json '{\"repo\":\"owner/repo\",\"pr\":123}'"

# Monitor PR and emit message only on change
$LOBSTER "workflows.run --name github.pr.monitor.notify --args-json '{\"repo\":\"owner/repo\",\"pr\":123}'"

Approval Flow (Tool Mode)

When a pipeline hits approve, it returns:

{
  "status": "needs_approval",
  "requiresApproval": {
    "prompt": "Send 3 emails?",
    "items": [...],
    "resumeToken": "eyJ..."
  }
}

To continue:

$LOBSTER resume --token "eyJ..." --approve yes

Example Pipelines

# List recent PRs, filter merged, show as table
$LOBSTER 'exec --json --shell "gh pr list --repo owner/repo --json number,title,state --limit 20" | where "state=MERGED" | table'

# Get data, require approval, then process
$LOBSTER run --mode tool 'exec --json --shell "echo [{\"id\":1},{\"id\":2}]" | approve --prompt "Process these?" | pick id | json'

# Diff against last run (only emit on change)
$LOBSTER 'exec --json --shell "gh pr view 123 --repo o/r --json state,title" | diff.last --key "pr:o/r#123" | json'

Workflow Files (.lobster)

YAML/JSON files with steps, conditions, and approval gates:

name: pr-review-reminder
steps:
  - id: fetch
    command: gh pr list --repo ${repo} --json number,title,reviewDecision
  - id: filter
    command: jq '[.[] | select(.reviewDecision == "")]'
    stdin: $fetch.stdout
  - id: notify
    command: echo "PRs needing review:" && cat
    stdin: $filter.stdout
    approval: required

Run: $LOBSTER run workflow.lobster --args-json '{"repo":"owner/repo"}'

Clawdbot Integration

Lobster can call Clawdbot tools via clawd.invoke:

$LOBSTER 'clawd.invoke --tool message --action send --args-json "{\"target\":\"123\",\"message\":\"hello\"}"'

Requires CLAWD_URL and CLAWD_TOKEN environment variables.

State Directory

Lobster stores state in ~/.lobster/state/ by default. Override with LOBSTER_STATE_DIR.

lobster

Lobster

CLI Location

Quick Reference