Quickstart

1. Install:

npm install -g @omicsos/lobster

2. Authenticate:

lobster cloud login

3. Ask anything:

lobster cloud query "Find differentially expressed genes in BRCA vs normal tissue" --stream

CLI Reference

Cloud queries — single-turn analysis against ECS Fargate agents:

lobster cloud query "your question"            # Run, wait, print result
lobster cloud query "your question" --stream   # Stream text as it arrives
lobster cloud query "your question" --json     # Machine-readable output
lobster cloud query "..." --session-id latest  # Continue previous session

Interactive cloud chat — full session with the Ink TUI:

lobster cloud chat                             # New session
lobster cloud chat --session-id <uuid>         # Resume session

Local chat — runs Python agents on your machine (requires lobster-ai):

lobster chat                                   # Delegates to Python engine

Setup & auth:

lobster init                                   # Interactive setup wizard
lobster cloud login                            # Browser OAuth or --api-key
lobster cloud status                           # Account, usage, budget
lobster -V                                     # Version info (npm + Python)

Commands

Sessions

| Command | Description | |---------|-------------| | lobster cloud session list | List recent sessions | | lobster cloud session info <id> | Show session details | | lobster cloud session archive <id> | Soft-delete a session | | lobster cloud session delete <id> [--force] | Permanently delete | | lobster cloud session share <id> | Create shareable URL | | lobster cloud session cancel <id> | Cancel in-progress run |

Files

| Command | Description | |---------|-------------| | lobster cloud files list <session-id> | List workspace files | | lobster cloud files upload <session-id> <path> | Upload local file | | lobster cloud files download <session-id> <key> [dest] | Download file | | lobster cloud files delete <session-id> <key> | Delete file | | lobster cloud files load <session-id> <path> | Load into session context |

BioVault

| Command | Description | |---------|-------------| | lobster cloud vault search --genes <A,B> --disease <D> --control <C> | Search evidence cache | | lobster cloud vault ask --genes <A,B> --disease <D> --control <C> | Submit analysis job | | lobster cloud vault evidence <id> | Get evidence card | | lobster cloud vault jobs | List your jobs | | lobster cloud vault export <id> --formats <pdf,csv> | Export artifacts |

Vector Search (Ontology Matching)

| Command | Description | |---------|-------------| | lobster cloud vector search "T cell exhaustion" | Semantic ontology search | | lobster cloud vector search "..." --collections mondo,uberon | Filter collections |

Exports & Editor

| Command | Description | |---------|-------------| | lobster cloud export <session-id> --type report | Export session as report/pipeline/slidedeck | | lobster cloud editor generate <session-id> | Generate LaTeX artifacts | | lobster cloud editor compile <session-id> | Compile to PDF | | lobster cloud editor download <session-id> | Download project ZIP |

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  lobster (npm)                                                   │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐                 │
│  │ @cli     │  │ @tui     │  │ @cloud-client │                 │
│  │ Commander│  │ React Ink│  │ Typed API SDK │                 │
│  └────┬─────┘  └────┬─────┘  └───────┬───────┘                 │
│       │              │                │                          │
├───────┼──────────────┼────────────────┼──────────────────────────┤
│       │              │                │                          │
│  lobster cloud *     │         DataStream (SSE)                  │
│       │              │                │                          │
│       ▼              ▼                ▼                          │
│  ┌─────────────────────────────────────────┐                    │
│  │        Omics-OS Cloud (ECS Fargate)     │                    │
│  │   22 specialist agents · managed LLMs   │                    │
│  └─────────────────────────────────────────┘                    │
│                                                                  │
├──────────────────────────────────────────────────────────────────┤
│  lobster chat →                                                  │
│       │                                                          │
│       ▼                                                          │
│  ┌─────────────────────────────────────────┐                    │
│  │     Python lobster-ai (local engine)    │                    │
│  │   LangGraph · your LLM keys · on-prem  │                    │
│  └─────────────────────────────────────────┘                    │
└─────────────────────────────────────────────────────────────────┘

Two modes, one binary:

• lobster cloud * — agents run on Omics-OS Cloud (ECS Fargate). No Python needed. Managed LLMs via AWS Bedrock.
• lobster chat — agents run locally via Python lobster-ai. Your keys, your hardware. Patient data never leaves your machine.

Local Mode

When Python lobster-ai is installed alongside the npm CLI, the full local engine is available:

pip install 'lobster-ai[full]'
lobster init          # Detects Python, configures provider + agents
lobster chat          # Local agents with your own LLM keys

The npm binary always wins PATH. Unrecognized commands are forwarded to Python automatically:

lobster config        # → python -m lobster config
lobster agents list   # → python -m lobster agents list

Available on all commands:

| Flag | Effect | |------|--------| | --json | Machine-readable JSON output | | --endpoint <url> | Override API endpoint | | --no-color | Disable ANSI colors | | --verbose | Show request details | | -V, --version | Show CLI + Python + cloud info |

Credentials stored at ~/.config/omics-os/credentials.json (mode 0600). Shared between npm CLI and Python lobster-ai.

OAuth (default):

lobster cloud login          # Opens browser, receives one-time code via localhost callback

API key:

lobster cloud login --api-key omk_...

Environment variable (CI/CD):

export OMICSOS_API_KEY=omk_...
lobster cloud query "..." --json

LOBSTER_TOKEN remains supported as a legacy fallback. Token refresh is automatic for OAuth. API keys don't expire.

Every cloud query creates or continues a session:

# New session (auto-created)
lobster cloud query "Load BRCA dataset from GEO"

# Continue most recent session
lobster cloud query "Now run differential expression" --session-id latest

# Resume specific session
lobster cloud query "Show results" --session-id 4a8f2c1d-...

Sessions persist server-side. View and manage them at app.omics-os.com.

# JSON output for parsing
lobster cloud query "List top 10 DEGs" --json | jq '.response'

# With explicit API key
OMICSOS_API_KEY=omk_... lobster cloud query "..." --json

# Check exit codes
lobster cloud query "..." --json
# 0 = success, 1 = error, 130 = cancelled (SIGINT)

Links