Skill: cewinharhar/lobsterbio-use (version 1.1.406)

--- name: lobster-use description: | Runs bioinformatics analysis with Lobster AI -- single-cell RNA-seq, bulk RNA-seq, genomics (VCF/GWAS), proteomics (mass spec/affinity), metabolomics (LC-MS/GC-MS/NMR), machine learning (feature selection, survival analysis), drug discovery, literature search, dataset discovery, and visualization. Use when working with biological data, omics analysis, or bioinformatics tasks. Covers: H5AD, CSV, VCF, PLINK, 10X, mzML formats, GEO/SRA/PRIDE/MetaboLights accessions. TRIGGER PHRASES: "analyze cells", "search PubMed", "download GEO", "run QC", "cluster", "find markers", "differential expression", "UMAP", "volcano plot", "single-cell", "RNA-seq", "VCF", "GWAS", "proteomics", "mass spec", "metabolomics", "MetaboLights", "LC-MS", "metabolite", "feature selection", "survival analysis", "biomarker", "bioinformatics", "drug discovery", "pharmacogenomics", "variant annotation" ASSUMES: Lobster is installed and configured. For setup issues, tell user to run `lobster config-test` and fix any errors before proceeding. required_binaries: - lobster - python3 primary_credential: LLM_PROVIDER_API_KEY required_env_vars: - name: ANTHROPIC_API_KEY required: one_of_provider description: Anthropic Claude API key - name: GOOGLE_API_KEY required: one_of_provider description: Google Gemini API key - name: OPENAI_API_KEY required: one_of_provider description: OpenAI API key - name: OPENROUTER_API_KEY required: one_of_provider description: OpenRouter API key (600+ models) - name: AWS_ACCESS_KEY_ID required: one_of_provider description: AWS Bedrock access key (must be paired with AWS_SECRET_ACCESS_KEY) - name: AWS_SECRET_ACCESS_KEY required: one_of_provider description: AWS Bedrock secret key (must be paired with AWS_ACCESS_KEY_ID) - name: AZURE_AI_ENDPOINT required: one_of_provider description: Azure AI endpoint URL (must be paired with AZURE_AI_CREDENTIAL) - name: AZURE_AI_CREDENTIAL required: one_of_provider description: Azure AI API credential (must be paired with AZURE_AI_ENDPOINT) - name: NCBI_API_KEY required: false description: NCBI API key for faster PubMed/GEO access (recommended) credential_note: | Exactly ONE LLM provider is required (not all). Choose one provider and set only that provider's env var(s). Paired credentials (AWS, Azure) must both be set. declared_writes: - .lobster_workspace/ # Workspace data, session state, outputs - .lobster_workspace/.env # Provider credential (workspace-scoped, mode 0600) - .lobster_workspace/provider_config.json # Provider selection config - ~/.config/lobster/credentials.env # ONLY if --global flag is used (not default) - ~/.config/lobster/providers.json # ONLY if --global flag is used (not default) network_access: - docs.omics-os.com # On-demand documentation fetches - LLM provider API endpoint # Whichever single provider is configured - eutils.ncbi.nlm.nih.gov # PubMed/GEO search (Research Agent only) - ftp.ncbi.nlm.nih.gov # GEO/SRA dataset downloads (Data Expert only) - www.ebi.ac.uk # PRIDE/MetaboLights (Research Agent only) source: github: https://github.com/the-omics-os/lobster pypi: https://pypi.org/project/lobster-ai/ always: false --- # Lobster AI Usage Guide Lobster AI is a multi-agent bioinformatics platform. Users describe analyses in natural language -- Lobster routes to 22 specialist agents across 10 packages automatically. ## Requirements - **Binaries**: `lobster` CLI (`pip install lobster-ai`), Python 3.12+ - **Credential**: Exactly ONE LLM provider key as env var (not all — pick one): - `ANTHROPIC_API_KEY` | `GOOGLE_API_KEY` | `OPENAI_API_KEY` | `OPENROUTER_API_KEY` - `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` (Bedrock — both required) - `AZURE_AI_ENDPOINT` + `AZURE_AI_CREDENTIAL` (Azure — both required) - Ollama: no key needed (local models) - **Optional**: `NCBI_API_KEY` for faster PubMed/GEO - **Writes**: `.lobster_workspace/` (data, credentials in `.env` mode 0600, outputs) - **Global config** (`--global` flag, NOT default): `~/.config/lobster/` — avoid unless needed - **Network**: LLM provider API + public bio databases (GEO, SRA, PRIDE, MetaboLights) ## Docs Discovery The docs site at **docs.omics-os.com** exposes LLM-friendly raw markdown: | Route | Use | |-------|-----| | `/llms.txt` | Index of all pages (title + URL + description) | | `/llms-full.txt` | Full content dump of all free pages | | `/raw/docs/{slug}.md` | Raw markdown for a specific page | **Workflow**: Fetch `/llms.txt` first to discover slugs, then fetch individual pages via `/raw/docs/{slug}.md`. Example: `https://docs.omics-os.com/raw/docs/tutorials/single-cell-rnaseq.md` ## Two Modes This skill supports coding agents in two modes: **Orchestrator** -- The agent calls `lobster query --json --session-id` programmatically, parses structured output, and chains multi-step analyses. See [agent-patterns.md](references/agent-patterns.md). **Guide** -- The agent teaches a human user what to type in `lobster chat` or `lobster query`. See the routing table below for which docs page to fetch. ## Quick Start ```bash # Install (PyPI -- preferred) pip install 'lobster-ai[full]' # or: uv tool install 'lobster-ai[full]' # Configure (uses env var -- never pass raw keys on command line) lobster init --non-interactive --anthropic-key "$ANTHROPIC_API_KEY" --profile production # Run analysis (always pass -w and --session-id together) lobster query -w ./my_analysis --session-id "proj" --json "Download GSE109564 and run QC" # Inspect workspace (no tokens burned, ~300ms) lobster command data --json -w ./my_analysis ``` **Source**: [github.com/the-omics-os/lobster](https://github.com/the-omics-os/lobster) | **PyPI**: [pypi.org/project/lobster-ai](https://pypi.org/project/lobster-ai/) ## Routing Table | You want to... | Docs slug | Skill reference | |---|---|---| | **Install & configure** | `getting-started/installation` | -- | | **Configuration options** | `getting-started/configuration` | -- | | **Use the CLI** | `guides/cli-commands` | [cli-reference.md](references/cli-reference.md) | | **Orchestrate programmatically** | -- | [agent-patterns.md](references/agent-patterns.md) | | **Analyze scRNA-seq** | `tutorials/single-cell-rnaseq` | -- | | **Analyze bulk RNA-seq** | `tutorials/bulk-rnaseq` | -- | | **Analyze proteomics** | `tutorials/proteomics` | -- | | **Understand data formats** | `guides/data-formats` | -- | | **Search literature / datasets** | `agents/research` | -- | | **Analyze genomics** | `agents/genomics` | -- | | **Analyze metabolomics** | `case-studies/metabolomics` | -- | | **ML / feature selection** | `agents/ml` | -- | | **Drug discovery** | `agents/drug-discovery` | -- | | **Visualize results** | `agents/visualization` | -- | | **Troubleshoot** | `support/troubleshooting` | -- | | **See case studies** | `case-studies/{domain}` | -- | | **All agent capabilities** | `agents` | -- | | **Extend Lobster (dev)** | -- | Use `lobster-dev` skill | To fetch a docs page: `https://docs.omics-os.com/raw/docs/{slug}.md` ## Hard Rules 1. **Always use `--session-id`** for multi-step analyses -- loaded data persists across queries 2. **Use `lobster command --json`** for workspace inspection (no tokens burned, ~300ms) 3. **Research Agent is the ONLY agent with internet access** -- all others operate on loaded data 4. **Never skip QC** before analysis -- always assess quality first 5. **Use `--json` flag** when parsing output programmatically 6. **Check data is loaded** before running analysis steps (`lobster command data --json`) 7. **Default workspace**: `.lobster_workspace/` -- override with `-w <path>` 8. **Fetch docs on demand** from `docs.omics-os.com/raw/docs/{slug}.md` -- don't guess workflows ## Agent Overview 22 agents across 10 packages. Supervisor routes automatically based on natural language. | Agent | Package | Handles | |---|---|---| | Supervisor | lobster-ai | Routes queries, coordinates agents | | Research Agent | lobster-research | PubMed, GEO, SRA, PRIDE, MetaboLights search (online) | | Data Expert | lobster-research | File loading, downloads, format conversion (offline) | | Transcriptomics Expert | lobster-transcriptomics | scRNA-seq + bulk RNA-seq: QC, clustering, trajectory | | Annotation Expert | lobster-transcriptomics | Cell type annotation, gene set enrichment (child) | | DE Analysis Expert | lobster-transcriptomics | Differential expression, pseudobulk, GSEA (child) | | Proteomics Expert | lobster-proteomics | MS + affinity import, QC, normalization, batch correction | | Proteomics DE Expert | lobster-proteomics | Protein DE, pathway enrichment, KSEA, STRING PPI (child) | | Biomarker Discovery | lobster-proteomics | Panel selection, nested CV, hub proteins (child) | | Metabolomics Expert | lobster-metabolomics | LC-MS/GC-MS/NMR: QC, normalization, PCA/PLS-DA, annotation | | Genomics Expert | lobster-genomics | VCF/PLINK: QC, GWAS, variant annotation | | Variant Analysis Expert | lobster-genomics | VEP annotation, ClinVar, clinical prioritization (child) | | ML Expert | lobster-ml | ML prep, scVI embeddings, data export | | Feature Selection Expert | lobster-ml | Stability selection, LASSO, variance filtering (child) | | Survival Analysis Expert | lobster-ml | Cox models, Kaplan-Meier, risk stratification (child) | | Drug Discovery Expert | lobster-drug-discovery | Drug target validation, compound profiling | | Cheminformatics Expert | lobster-drug-discovery | Molecular descriptors, fingerprints, similarity (child) | | Clinical Dev Expert | lobster-drug-discovery | Trial design, endpoint analysis, safety signals (child) | | Pharmacogenomics Expert | lobster-drug-discovery | PGx variants, drug-gene interactions (child) | | Visualization Expert | lobster-visualization | UMAP, heatmaps, volcano plots, dot plots (Plotly) | | Metadata Assistant | lobster-metadata | ID mapping, metadata standardization (internal) | | Protein Structure Viz | lobster-structural-viz | PDB fetch, PyMOL visualization, RMSD | Per-agent docs: `https://docs.omics-os.com/raw/docs/agents/{domain}.md`

path: references/agent-patterns.md
content: # Agent Orchestration Patterns

How coding agents (Claude Code, Gemini CLI, Codex, OpenClaw) use Lobster AI programmatically
to offload bioinformatics analysis.

## Core Pattern

The agent calls `lobster query --json --session-id` and parses structured output:

```bash
RESULT=$(lobster query --session-id "proj" --json "Your analysis request")
echo "$RESULT" | jq -r '.response'
```

**Key flags for agents**:
- `--json` -- structured JSON on stdout (Rich UI goes to stderr)
- `--session-id <id>` -- data persists across queries (REQUIRED for multi-step)
- `-w <path>` -- explicit workspace path
- `--no-stream` -- default for `query`, returns complete result

## JSON Output Schema

**Success response**:
```json
{
  "success": true,
  "response": "Analysis complete. Found 15,234 cells...",
  "session_id": "proj",
  "last_agent": "transcriptomics_expert",
  "token_usage": { ... }
}
```

**Error response**:
```json
{
  "success": false,
  "response": "",
  "session_id": "proj",
  "error": "No modality loaded. Load data first."
}
```

**Fields**: `success` and `response` always present. `last_agent` and `token_usage` only on success.
`workspace` is NOT included in the JSON output — track it yourself from `-w`.

Parse with: `jq -r '.response'`

## Workspace Inspection (No Tokens)

Use `lobster command --json` for fast inspection (~300ms, no LLM, no API keys):

```bash
# What data is loaded?
lobster command data --json -w .lobster_workspace | jq '.data'

# List workspace files
lobster command files --json -w .lobster_workspace | jq '.data.tables'

# List available datasets
lobster command "workspace list" --json | jq '.data.tables[0].rows'

# Modality details
lobster command modalities --json | jq '.data'

# Check system status
lobster config-test --json
```

**Rule**: Always use `lobster command` for inspection. Only use `lobster query` for
analysis that requires the agent system.

## Multi-Step Analysis Pattern

A typical orchestrated pipeline:

```bash
SESSION="liver_study"
WORKSPACE="./liver_analysis"

# IMPORTANT: Always pass BOTH -w and --session-id on EVERY call.
# Omitting -w causes workspace to default to .lobster_workspace/ and lose context.

# Step 1: Search (Research Agent -- online)
lobster query -w "$WORKSPACE" --session-id "$SESSION" --json \
  "Search PubMed for liver fibrosis scRNA-seq datasets from 2023-2024"

# Step 2: Download (Data Expert -- executes queued download)
lobster query -w "$WORKSPACE" --session-id "$SESSION" --json \
  "Download the top dataset"

# Step 3: Verify data loaded before proceeding
DATA=$(lobster command data --json -w "$WORKSPACE")
if ! echo "$DATA" | jq -e '.success' > /dev/null 2>&1; then
  echo "No data loaded yet -- check download status"
  lobster command "queue list" --json -w "$WORKSPACE"
  exit 1
fi

# Step 4: Analyze (Transcriptomics Expert)
lobster query -w "$WORKSPACE" --session-id "$SESSION" --json \
  "Run QC, filter low-quality cells, normalize, and cluster"

# Step 5: Annotate (Annotation Expert -- child of Transcriptomics)
lobster query -w "$WORKSPACE" --session-id "$SESSION" --json \
  "Identify cell types in each cluster"

# Step 6: DE (DE Analysis Expert -- child of Transcriptomics)
lobster query -w "$WORKSPACE" --session-id "$SESSION" --json \
  "Find differentially expressed genes between hepatocytes and stellate cells"

# Step 7: Visualize (Visualization Expert)
lobster query -w "$WORKSPACE" --session-id "$SESSION" --json \
  "Create UMAP colored by cell type and export marker genes to CSV"

# Step 8: Check outputs
lobster command files --json -w "$WORKSPACE"
```

## Non-Interactive Setup

Before first use, initialize Lobster without user interaction.
**Always pass API keys via environment variables** — never hardcode secrets.

```bash
# Check if already configured
if ! lobster config-test --json 2>/dev/null | jq -e '.success' > /dev/null 2>&1; then
  # Requires ANTHROPIC_API_KEY set in environment
  lobster init --non-interactive --anthropic-key "$ANTHROPIC_API_KEY" --profile production
fi
```

For all provider options, see [cli-reference.md](cli-reference.md) "Initialization" section.

## Output File Discovery

Lobster writes outputs to the workspace. When you pass `-w ./my_analysis`, the workspace
root is `./my_analysis/.lobster_workspace/`. When you omit `-w`, the default is
`.lobster_workspace/` in the current directory.

```bash
# Use lobster command to discover outputs (preferred -- no tokens)
lobster command files --json -w "$WORKSPACE"
lobster command plots --json -w "$WORKSPACE"

# Or find files directly
WS_DIR="${WORKSPACE}/.lobster_workspace"
find "$WS_DIR" -name "*.h5ad"   # Processed AnnData objects
find "$WS_DIR" -name "*.html"   # Interactive Plotly visualizations
find "$WS_DIR" -name "*.png"    # Publication-ready plots
find "$WS_DIR" -name "*.csv"    # Exported tables
find "$WS_DIR" -name "*.ipynb"  # Reproducible notebooks
```

## Pipeline Export

Export a completed analysis as a reproducible Jupyter notebook:

```bash
# Export from a named session
lobster command "pipeline export" --session-id "$SESSION"

# The notebook appears in the workspace
ls "$WORKSPACE"/*.ipynb
```

## Error Handling

Check the `success` field in JSON output. **Do NOT redirect stderr** — it contains
diagnostic information needed for debugging.

```bash
# Capture stdout (JSON) and stderr (diagnostics) separately
RESULT=$(lobster query -w "$WORKSPACE" --session-id "$SESSION" --json "Run clustering" 2>lobster_stderr.log)
SUCCESS=$(echo "$RESULT" | jq -r '.success // false')

if [ "$SUCCESS" != "true" ]; then
  echo "Analysis failed"
  echo "$RESULT" | jq -r '.error // .response // "Unknown error"'
  cat lobster_stderr.log  # Check for Python tracebacks or startup errors
  exit 1
fi
```

**If `jq` is not available**, use Python as fallback:
```bash
echo "$RESULT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('response',''))"
```

Common failure patterns:
- **No data loaded**: Agent ran analysis before loading data. Use `lobster command data --json -w "$WORKSPACE"` to verify.
- **Session not found**: Missing `--session-id` on a follow-up query. Data from previous queries is lost.
- **Workspace mismatch**: Omitting `-w` on a follow-up causes default workspace, losing context. Always pass `-w`.
- **Agent not available**: Package not installed. Check with `lobster agents list`.
- **Config error**: Run `lobster config-test --json` to diagnose.
- **Download pending**: Data queued but not yet downloaded. Check `lobster command "queue list" --json -w "$WORKSPACE"`.

## Combining Lobster with Other Tools

Lobster handles the bioinformatics. The coding agent handles everything else:

```bash
# Extract specific values from Lobster's response
CELL_COUNT=$(lobster query --session-id "$SESSION" --json \
  "How many cells passed QC?" | jq -r '.response' | grep -oP '\d+(?= cells)')

# Use Lobster output files in downstream scripts
lobster query --session-id "$SESSION" --json "Export DE results to CSV"
RESULTS_CSV=$(find .lobster_workspace -name "*de_results*" -name "*.csv" | head -1)
python my_custom_analysis.py "$RESULTS_CSV"

# Feed external data into Lobster
lobster query -w ./analysis --session-id "ext" --json \
  "Load the data from /path/to/external_data.h5ad"
```

## Agent Routing

You don't need to specify which agent to use. Describe the task in natural language
and Lobster routes automatically. Key routing rules:

- **Literature/dataset search** -> Research Agent (ONLY agent with internet)
- **File loading/downloading** -> Data Expert (offline only)
- **scRNA-seq / bulk RNA-seq** -> Transcriptomics Expert
- **Proteomics (any platform)** -> Proteomics Expert
- **Metabolomics** -> Metabolomics Expert
- **VCF / PLINK / GWAS** -> Genomics Expert
- **Plots and figures** -> Visualization Expert
- **ML, feature selection** -> ML Expert
- **Drug targets, compounds** -> Drug Discovery Expert

## Session Continuity Best Practices

1. **Always name sessions**: `--session-id "descriptive_name"` not random IDs
2. **One session per analysis**: Don't mix unrelated analyses in one session
3. **Check before continuing**: `lobster command data --json` after resuming
4. **Use `latest` sparingly**: Prefer explicit session names for reproducibility
5. **Workspace + session together**: `-w ./project --session-id "run_01"`


path: references/cli-reference.md
content: # CLI Reference

Complete reference for the Lobster AI command-line interface.

**Source**: [github.com/the-omics-os/lobster](https://github.com/the-omics-os/lobster) |
**PyPI**: [pypi.org/project/lobster-ai](https://pypi.org/project/lobster-ai/) |
**Docs**: `https://docs.omics-os.com/raw/docs/guides/cli-commands.md`

## Installation

| Method | Command |
|--------|---------|
| pip (recommended) | `pip install 'lobster-ai[full]' && lobster init` |
| uv tool (isolated) | `uv tool install 'lobster-ai[full]' && lobster init` |
| Targeted domain | `pip install 'lobster-ai[proteomics]'` (lighter) |

**Targeted extras**: `[proteomics]`, `[genomics]`, `[transcriptomics]` — each includes research + viz agents.

**Upgrade**: `pip install --upgrade lobster-ai` or `uv tool upgrade lobster-ai`

**Add agents (uv tool)**: `uv tool install lobster-ai --with lobster-proteomics --with lobster-genomics`

## Initialization (`lobster init`)

`lobster init` is an **interactive wizard** -- coding agents cannot run it directly.

**Non-interactive init** (agents can run this):

**Credential safety**: Always pass API keys via environment variables, never as raw strings.
Keys are written to workspace `.env` (mode 0600) or `~/.config/lobster/credentials.env`.

```bash
# Anthropic (most common)
lobster init --non-interactive --anthropic-key "$ANTHROPIC_API_KEY" --profile production

# Google Gemini
lobster init --non-interactive --gemini-key "$GOOGLE_API_KEY"

# OpenAI
lobster init --non-interactive --openai-key "$OPENAI_API_KEY"

# AWS Bedrock
lobster init --non-interactive --bedrock-access-key "$AWS_ACCESS_KEY_ID" --bedrock-secret-key "$AWS_SECRET_ACCESS_KEY"

# Ollama (local, no API key)
lobster init --non-interactive --use-ollama --ollama-model "llama3:8b-instruct"

# OpenRouter (600+ models)
lobster init --non-interactive --openrouter-key "$OPENROUTER_API_KEY"

# Azure AI
lobster init --non-interactive --azure-endpoint "$AZURE_AI_ENDPOINT" --azure-credential "$AZURE_AI_CREDENTIAL"
```

**Non-interactive flags**:

| Flag | Purpose |
|------|---------|
| `--profile <name>` | `development`, `production`, `performance`, `max` (Anthropic/Bedrock) |
| `--ncbi-key <key>` | NCBI API key for faster PubMed/GEO (via env var) |
| `--agents <list>` | Comma-separated agent names |
| `--preset <name>` | `scrna-basic`, `scrna-full`, `multiomics-full` |
| `--skip-extras` | Skip all optional packages |
| `--skip-ssl-test` | Skip SSL connectivity test |
| `--skip-docling` | Skip PDF intelligence install |
| `--install-docling` | Install docling |

**Advanced flags** (use with caution):

| Flag | Purpose |
|------|---------|
| `--global` | Save to `~/.config/lobster/` instead of workspace — writes global config |
| `--force` | Overwrite existing config (creates timestamped backup first) |
| `--cloud-key <key>` | Omics-OS Cloud API key (premium tier) |

**Check if already configured**:
```bash
lobster config-test --json    # Structured status
lobster status                # Human-readable
```

**Config file locations**:

| Mode | Config | Credentials |
|------|--------|-------------|
| Workspace (default) | `.lobster_workspace/provider_config.json` | `.env` |
| Global (`--global`) | `~/.config/lobster/providers.json` | `~/.config/lobster/credentials.env` |

**Priority**: workspace `.env` > global `credentials.env` > environment variables

## Top-Level Commands

| Command | Description |
|---------|-------------|
| `lobster chat` | Interactive chat (Go TUI by default) |
| `lobster query "..."` | Single-turn query |
| `lobster command <cmd>` | Execute slash command without LLM (~300ms) |
| `lobster init` | Configuration wizard |
| `lobster status` | Tier, packages, agents |
| `lobster config-test` | Test API connectivity |
| `lobster agents list` | List installed agent packages |
| `lobster agents info <name>` | Agent package details |
| `lobster serve --port 8080` | Start API server |
| `lobster dashboard` | Visual monitoring UI |
| `lobster purge` | Remove Lobster files (`--dry-run`, `--force`) |

## `lobster chat`

Interactive mode. **Go TUI** (Charm stack) is the default terminal experience.

```bash
lobster chat                        # Default (Go TUI auto-detected)
lobster chat --ui classic           # Force legacy Rich/Textual mode
lobster chat --classic              # Shorthand for --ui classic
lobster chat --no-intro             # Skip welcome animation
lobster chat -w ./my_analysis       # Set workspace
lobster chat -s "my_session"        # Continue named session
lobster chat --reasoning            # Show agent reasoning
```

**Go TUI features**:
- Tab completion for all 28+ slash commands and subcommands
- Dynamic completion for file paths and modality names
- Streaming markdown rendering (Glamour)

| Flag | Default | Description |
|------|---------|-------------|
| `-w, --workspace <path>` | auto | Workspace directory |
| `-s, --session-id <id>` | (none) | Named session to continue |
| `--ui <mode>` | auto | `go`, `classic`, or `auto` |
| `--classic` | -- | Shorthand for `--ui classic` |
| `--no-intro` | off | Skip intro animation |
| `--reasoning` | off | Show agent reasoning |
| `--stream/--no-stream` | on | Streaming (on by default in chat) |
| `-v, --verbose` | off | Debug output |
| `-p, --provider <name>` | config | Override LLM provider |
| `-m, --model <name>` | config | Override model |

## `lobster query`

Single-turn queries. Returns complete result by default (no streaming).

```bash
lobster query "Search PubMed for CRISPR in cancer"
lobster query --session-id "proj" "Download GSE109564"
lobster query --session-id "proj" "Run QC and cluster"
lobster query --session-id latest "Continue analysis"
lobster query --json "What data is loaded?" | jq .response
lobster query --output results.md "Generate report"
```

| Flag | Default | Description |
|------|---------|-------------|
| `--session-id <id>` | (none) | Session continuity (required for multi-step) |
| `--session-id latest` | -- | Continue most recent session |
| `-w, --workspace <path>` | auto | Workspace directory |
| `-o, --output <file>` | (none) | Write response to file |
| `-j, --json` | off | Structured JSON on stdout |
| `--stream/--no-stream` | off | Streaming (off by default in query) |
| `--reasoning` | off | Show agent reasoning |
| `-v, --verbose` | off | Debug output |
| `-p, --provider <name>` | config | Override LLM provider |
| `-m, --model <name>` | config | Override model |

## `lobster command` (Programmatic Access)

Execute slash commands **without starting an LLM session**. No API keys needed. ~300ms.

```bash
lobster command data --json                          # Current dataset info
lobster command "workspace list" --json              # List datasets
lobster command files --json                         # List workspace files
lobster command "pipeline export" --session-id proj  # Export notebook
lobster command modalities --json                    # Modality details
```

Leading `/` is stripped automatically (`lobster command /data` = `lobster command data`).

**JSON output schema**:
```json
{
  "success": true,
  "command": "workspace list",
  "data": {
    "tables": [{"title": "...", "columns": ["..."], "rows": [["..."]]}],
    "messages": [{"text": "...", "style": "info"}]
  },
  "summary": "Listed 3 available datasets"
}
```

## Slash Commands (Interactive & `lobster command`)

### Data & Files

| Command | Description |
|---------|-------------|
| `/data` | Current dataset info (shape, columns, stats) |
| `/files` | List workspace files by category |
| `/tree` | Directory tree view |
| `/read <file>` | View file contents (pattern support: `*.json`) |
| `/open <file>` | Open in system default app |
| `/plots` | List generated visualizations |
| `/modalities` | Detailed modality information |
| `/describe <name>` | Statistical summary of a modality |

### Workspace Management

| Command | Description |
|---------|-------------|
| `/workspace` | Workspace status |
| `/workspace list` | List available datasets with index numbers |
| `/workspace info <sel>` | Dataset details by index or name |
| `/workspace load <sel>` | Load dataset by index, pattern, or file path |
| `/workspace remove <sel>` | Remove modality |
| `/workspace save` | Save modalities to workspace |
| `/restore` | Restore recent datasets from session |
| `/restore all` | Restore all available datasets |

### Queue

| Command | Description |
|---------|-------------|
| `/queue` | Download and publication queue status |
| `/queue list [type]` | List queued items (`publication`, `download`) |
| `/queue clear [type]` | Clear queue entries |
| `/queue export` | Export queue to CSV |
| `/queue load <file>` | Load file into queue (supports .ris) |

### Metadata

| Command | Description |
|---------|-------------|
| `/metadata` | Smart metadata overview |
| `/metadata publications` | Publication queue breakdown |
| `/metadata samples` | Sample statistics and disease coverage |
| `/metadata workspace` | File inventory across storage locations |
| `/metadata exports` | Export files with categories |
| `/metadata list` | Detailed metadata list |
| `/metadata clear` | Clear metadata entries |

### Pipeline

| Command | Description |
|---------|-------------|
| `/pipeline list` | List available notebooks |
| `/pipeline info` | Notebook details |
| `/pipeline export` | Export reproducible Jupyter notebook (needs `--session-id`) |
| `/pipeline run` | Run exported notebook (needs `--session-id`) |

### Session & State

| Command | Description |
|---------|-------------|
| `/session` | Current session info (ID, messages, data) |
| `/save [--force]` | Save all modalities to workspace |
| `/export [--no-png]` | Export session data + plots to `exports/` |
| `/clear` | Clear conversation history |
| `/reset` | Reset conversation (retains loaded data) |
| `/status` | Subscription tier, packages, agents |
| `/tokens` | Token usage and costs |

### Configuration (Runtime)

| Command | Description |
|---------|-------------|
| `/config` | Show current configuration |
| `/config show` | Show provider, model, config files |
| `/config provider list` | List available LLM providers |
| `/config provider <name>` | Switch provider at runtime |
| `/config provider <name> --save` | Switch and persist to config |
| `/config model list` | List available models |
| `/config model <name>` | Switch model at runtime |
| `/config model <name> --save` | Switch and persist |

### Config CLI Subcommands

```bash
lobster config show           # Display current config
lobster config test           # Test LLM connectivity
lobster config list-models    # List model presets
lobster config list-profiles  # List testing profiles
lobster config show-config    # Full runtime config
lobster config create-custom  # Interactive custom config
lobster config models         # Per-agent model config
lobster config generate-env   # Generate .env template
```

## Session Management

```bash
# Named session (persisted to disk)
lobster query --session-id "cancer_project" "Load data"
lobster query --session-id "cancer_project" "Run QC"

# Continue most recent session
lobster query --session-id latest "Next step"

# Cross-session pipeline export
lobster command "pipeline export" --session-id cancer_project
```

**Workspace isolation**: different `-w` paths = separate sessions.

## LLM Providers

7 providers supported:

| Provider | Init flag | Env var |
|----------|-----------|---------|
| Anthropic | `--anthropic-key` | `ANTHROPIC_API_KEY` |
| AWS Bedrock | `--bedrock-access-key` + `--bedrock-secret-key` | `AWS_BEDROCK_ACCESS_KEY` |
| Google Gemini | `--gemini-key` | `GOOGLE_API_KEY` |
| OpenAI | `--openai-key` | `OPENAI_API_KEY` |
| Ollama (local) | `--use-ollama` | -- |
| OpenRouter | `--openrouter-key` | `OPENROUTER_API_KEY` |
| Azure AI | `--azure-endpoint` + `--azure-key` | `AZURE_ENDPOINT` |

## Keyboard Shortcuts (Interactive)

| Shortcut | Action |
|----------|--------|
| Ctrl+C | Cancel current operation |
| Ctrl+D | Exit |
| Ctrl+L | Clear screen |
| Ctrl+R | Search command history |
| Tab | Autocomplete commands, files, datasets |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)