CLI Commands Reference

Overview

Lobster AI provides a rich command-line interface with enhanced features including Tab completion, command history, and context-aware suggestions. The CLI supports both slash commands for system operations and natural language for analysis tasks.

Getting Started

Starting Lobster AI

# Start interactive chat mode
lobster chat

# Start with custom workspace
lobster chat --workspace /path/to/my/workspace

# Enable detailed agent reasoning
lobster chat --reasoning

# Enable verbose output for debugging
lobster chat --verbose

# Start with all debugging features
lobster chat --reasoning --verbose --debug

Workspace prompt (v1.0.7+): When chat starts, the prompt shows installed capabilities:

  ● lobster v1.0.7 free │ 8 agents │ semantic │ local │ /help

The semantic badge appears when the vector-search extra is installed. Without it, the badge is omitted.

Single Query Mode

# Execute a single query and exit
lobster query "Analyze my single-cell data"

# Save output to file
lobster query "Generate QC report" --output results.md

# Use custom workspace
lobster query "Load data.h5ad" --workspace /my/data

# Continue a named session (v1.0.7+)
lobster query --session-id "liver_study" "Download GSE109564"

# Resume the most recent session (v1.0.7+)
lobster query --session-id latest "Run clustering on the filtered data"

Dashboard Mode

# Launch interactive Textual-based dashboard
lobster dashboard

# With custom workspace
lobster dashboard --workspace /path/to/workspace

The dashboard provides a cockpit-style interface with:

• Real-time agent activity monitoring
• Live handoff visualization
• Query input with streaming responses
• Token usage and system status panels

API Server Mode

# Start API server for web interfaces
lobster serve

# Custom host and port
lobster serve --host 0.0.0.0 --port 8080

Interactive Features

Enhanced Input Capabilities

Arrow Key Navigation (requires prompt-toolkit):

• ←/→: Navigate within your input text
• ↑/↓: Browse command history
• Ctrl+R: Reverse search through history
• Home/End: Jump to beginning/end of line

Tab Completion:

• Commands: Type / and press Tab to see all commands
• Files: Tab completion after /read, /plot, /open
• Context-Aware: Smart suggestions based on current context
• Cloud Integration: Works with both local and cloud clients

Command History:

• Persistent: Commands saved between sessions
• Search: Use Ctrl+R to find previous commands
• Edit: Recall and modify previous commands

Installation for Enhanced Features

# Install optional dependency for full features
pip install prompt-toolkit

System Commands

Help and Information

/help

Display comprehensive help with all available commands.

/help

Shows categorized list of commands with descriptions and examples.

/session

Show current session status including conversation state and loaded data.

/session

Output includes:

• Session ID
• Mode/profile (development, production, ultra, godmode)
• Message count in conversation
• Workspace path
• Data loaded status (✓/✗)
• Data shape (rows × columns) if data is loaded
• Memory usage if data is loaded

/status

Show installation status, subscription tier, installed packages, and available agents.

/status

Output includes:

• Initialization status (.env configuration)
• LLM provider detection
• Subscription tier (🆓 Free, ⭐ Premium, 🏢 Enterprise)
• License source and expiration
• Installed packages table
• Available agents for your tier
• Premium agents (upgrade required)
• Enabled features
• Optional Capabilities (Semantic Search, Document Intelligence)

Optional Capabilities example (v1.0.7+):

Optional Capabilities:
  ✓  Semantic Search         chromadb + sentence-transformers
  ○  Document Intelligence   pip install 'lobster-ai[docling]'

Note: This command shows the same information as the CLI lobster status command.

/input-features

Display available input features and navigation capabilities.

/input-features

Shows status of Tab completion, arrow navigation, and command history.

Workspace Management

/workspace

Show comprehensive workspace information.

/workspace

Displays:

• Workspace path and configuration
• Loaded modalities and backends
• Directory structure and usage

/workspace list

List all available datasets in workspace without loading them.

/workspace list

Shows datasets with:

• Index Number (#) - Use for quick loading with /workspace load or /workspace info
• Status - ✓ (loaded) or ○ (available)
• Name - Intelligently truncated with middle-ellipsis for long names (max 60 chars)
• Size - Dataset size in MB
• Shape - Observations × variables
• Modified - Last modification date

Features (v0.2+):

• Numbered index for each dataset (1, 2, 3...) enables index-based loading
• Smart truncation preserves start and end of long dataset names
• Example: geo_gse155698_quality_assess...ted_clustered_markers
• Contextual help footer: "Use '/workspace info <#>' to see full details"
• Fixed column widths for professional table formatting

/workspace info <#|pattern>

Show detailed information for specific dataset(s) (v0.2+).

/workspace info 1                      # Show details for first dataset (index)
/workspace info gse12345              # Show details by name pattern
/workspace info *clustered*           # Show details for matching datasets

Input Options:

• Index number: Use # from /workspace list (e.g., 1, 5, 10)
• Name pattern: Full or partial dataset name
• Glob pattern: Wildcards for multiple matches (e.g., *liver*, geo_*)

Detailed Output:

• Full dataset name (no truncation)
• Load status (✓ Loaded / ○ Not Loaded)
• Complete file path
• Precise size in MB
• Shape with formatted numbers (e.g., 50,000 observations × 20,000 variables)
• File type (H5AD, MuData, etc.)
• Modification timestamp
• Detected processing stages (quality, filter, normal, doublet, cluster, marker, annot, pseudobulk)

Features:

• Index-based selection for convenience (no typing long names)
• Pattern matching with wildcards for flexibility
• Multiple datasets displayed when pattern matches many
• Automatic lineage detection from dataset naming convention

Example:

/workspace info 1

Dataset #1 Details:
────────────────────────────────────────────────────────────
Name:        geo_gse155698_quality_assessed_filtered_normalized_doublets_detected_clustered_markers
Status:      ✓ Loaded
Path:        /workspace/geo_gse155698_quality_assessed_filtered_normalized_doublets_detected_clustered_markers.h5ad
Size:        287.4 MB
Shape:       94,371 observations × 32,738 variables
Type:        H5AD
Modified:    2025-01-10 14:23:45
Stages:      quality → filter → normal → doublet → cluster → marker

/workspace load <#|pattern>

Load specific dataset(s) from workspace by index or pattern (v0.2+).

/workspace load 1                     # Load first dataset (index-based)
/workspace load 5                     # Load fifth dataset
/workspace load my_dataset            # Load by name
/workspace load *clustered*           # Load all matching pattern

Input Options:

• Index number: Use # from /workspace list - fast and convenient
• Name pattern: Full or partial dataset name for targeted loading
• Glob pattern: Wildcards for loading multiple related datasets

Features:

• Index-based loading (v0.2+): No need to type long dataset names
• Pattern matching: Load multiple datasets matching criteria
• Progress tracking: Shows loading progress for each dataset
• Automatic validation: Data quality checks during load
• Smart caching: Efficient memory usage

When to use:

• Use /workspace load <#> for loading single datasets by index (fastest)
• Use /workspace load <pattern> for loading specific datasets by name
• Use /restore for session continuation and bulk loading workflows

/restore [pattern]

Restore datasets from workspace based on pattern matching.

/restore                    # Restore recent datasets (default)
/restore recent            # Same as above
/restore all               # Restore all available datasets
/restore my_dataset        # Restore specific dataset by name
/restore *liver*           # Restore datasets matching pattern
/restore geo_*             # Restore all GEO datasets

Features:

• Tab completion for dataset names
• Flexible pattern matching support
• Shows loading progress with detailed summaries
• Intelligent memory management
• Session continuation support
• Works WITHOUT prior /save command - uses automatic session tracking

How It Works:

• recent mode: Reads from .session.json (automatically updated whenever you load data or perform operations)
• all mode: Scans workspace directory for all .h5ad files
• Pattern mode: Uses glob matching against workspace files

Pattern Options:

• recent - Load most recently used datasets from automatic session tracking (default)
• all or * - Load all available datasets from workspace scan
• <dataset_name> - Load specific dataset by exact name
• <partial_name>* - Load datasets matching partial name pattern

Note: Use /restore for session continuation and bulk loading workflows. Use /workspace load (v0.2+) for targeted single-dataset loading by index or specific pattern.

Relationship with /save:

• /restore does NOT require prior /save - session tracking is automatic
• /save creates explicit backup snapshots (with _autosave suffix)
• /restore recent loads from your original working files, not autosaves
• Use /save before risky operations, /restore for session continuation

File Operations

/files

List all files in workspace organized by category.

/files

Categories:

• Data: Analysis datasets and input files
• Exports: Generated output files
• Cache: Temporary and cached files

/tree

Show directory tree view of current location and workspace.

/tree

Displays nested folder structure with file counts and sizes.

/read <file>

View and inspect file contents (text files, code, configs). This is for inspection only - it does not load data for analysis.

/read config.yaml                  # View configuration file
/read results.csv                  # Preview CSV contents
/read script.py                    # View code with syntax highlighting
/read *.json                       # View all JSON files (glob pattern)

Supported Patterns:

• *: Match any characters
• ?: Match single character
• [abc]: Match any of a, b, or c

Features:

• Tab completion for file names
• Syntax highlighting for code files
• Binary file detection (shows file info instead)
• File size limits (10MB for text display)
• Glob pattern support for multiple files

When to Use:

• Use /read to inspect file contents before loading
• Use /workspace load <file> to load data for analysis
• Use natural language ("load my_data.h5ad") to load data for analysis

Note: /read is view-only. For data files (H5AD, large CSV), it shows file info and suggests using /workspace load instead.

/archive <file>

Load data from compressed archives containing bioinformatics data.

/archive GSE155698_RAW.tar         # Load 10X Genomics samples
/archive kallisto_results.tar.gz   # Load Kallisto quantification
/archive salmon_quant.zip          # Load Salmon quantification

Supported Archive Formats:

• TAR (.tar, .tar.gz, .tar.bz2)
• ZIP (.zip)

Supported Data Formats:

• 10X Genomics: Both V2 (genes.tsv) and V3 (features.tsv) chemistry
  • Handles compressed and uncompressed files
  • Automatic sample detection and concatenation
• Kallisto Quantification: Multiple samples with abundance.tsv or abundance.h5
• Salmon Quantification: Multiple samples with quant.sf
• GEO RAW Files: GSM-prefixed expression files

Features:

• Smart content detection without full extraction
• Automatic format identification
• Memory-efficient processing
• Handles nested archive structures
• Sample concatenation for multi-sample archives
• Compressed file support (.gz, .bz2)

Example Workflow:

/archive /path/to/GSE155698_RAW.tar
# Automatically detects:
# - 17 10X Genomics samples (V2 and V3 mixed)
# - Loads and concatenates all samples
# - Result: 94,371 cells × 32,738 genes

When to Use /archive vs /workspace load:

• Use /archive for: Compressed archives with multiple samples or nested structures
• Use /workspace load for: Individual data files already in workspace
• Use natural language ("load my_data.h5ad") for: New files not yet in workspace

/open <file>

Open file or folder in system default application.

/open results.pdf                  # Open in default PDF viewer
/open plots/                       # Open directory in file manager
/open .                            # Open current directory

Works with workspace files, absolute paths, and relative paths.

Data Management

/data

Show comprehensive summary of currently loaded data.

/data

For Single Modality:

• Shape (observations × variables)
• Data type and memory usage
• Quality metrics
• Metadata columns
• Processing history

For Multiple Modalities:

• Individual modality summaries
• Combined statistics
• Cross-modality information

/metadata

Show detailed metadata information including cached GEO data.

/metadata

Displays:

• Metadata Store: Cached GEO and external datasets
• Current Data Metadata: Active dataset information
• Validation Results: Data quality assessments

/modalities

Show detailed information for each loaded modality.

/modalities

For Each Modality:

• Observation and variable columns
• Data layers and embeddings
• Unstructured annotations
• Shape and memory information

Visualization

/plots

List all generated plots with metadata.

/plots

Shows plot ID, title, source, and creation time for all generated visualizations.

/plot [ID]

Open plots directory or specific plot.

/plot                              # Open plots directory
/plot plot_1                       # Open specific plot by ID
/plot "Quality Control"            # Open plot by title (partial match)

Features:

• Opens HTML version preferentially (interactive)
• Falls back to PNG if HTML unavailable
• Tab completion for plot IDs and titles

Session Management

/save

Save current state including all loaded data and generated plots.

/save

Saves:

• All loaded modalities as H5AD files (with _autosave suffix)
• Generated plots in HTML and PNG formats
• Processing log and tool usage history
• Session metadata

Important Notes:

• Explicit /save is NOT required for /restore to work - Lobster automatically tracks your session via .session.json
• Use /save when you want to:
  • Create explicit backup snapshots before risky operations
  • Export data with specific naming for archival purposes
  • Preserve a clean checkpoint state
• Session tracking happens automatically whenever you load data or perform operations
• Autosaved files are named <modality_name>_autosave.h5ad to distinguish from working files

/export

Export complete session data as a comprehensive package.

/export

Creates timestamped ZIP file with all data, plots, metadata, and analysis history.

/pipeline export (v1.0.7+)

Export a reproducible Jupyter notebook from your analysis provenance.

/pipeline export

Generates a notebook containing every analysis step as executable Python code, ready to reproduce your results.

Cross-session export (from lobster command):

lobster command "pipeline export" --session-id liver_study
lobster command "pipeline export" --session-id latest

See Session Continuity for details on exporting across terminal restarts.

/pipeline list

List available exported notebooks in the workspace.

/pipeline list

/pipeline run <notebook>

Execute an exported notebook against a modality.

/pipeline run my_pipeline.ipynb my_modality

/reset

Reset conversation and clear loaded data (with confirmation).

/reset

Prompts for confirmation before clearing:

• Conversation history
• Loaded modalities
• Generated plots
• Analysis state

Session Continuity (v1.0.7+)

Lobster AI persists your analysis provenance to disk when you use --session-id. This means you can close your terminal, restart your machine, and later export a reproducible Jupyter notebook from that session — without re-running the analysis.

The --session-id Flag

Use --session-id (or -s) with lobster query or lobster command to name and resume sessions:

# Start a named session
lobster query --session-id "liver_study" "Download GSE109564 and assess quality"

# Continue the same session in a new terminal
lobster query --session-id "liver_study" "Filter and normalize the data"

# Resume the most recent session (any name)
lobster query --session-id latest "Cluster the cells"

Cross-Session Pipeline Export

Because provenance is saved to disk, you can export notebooks from completed sessions at any time:

# Export a notebook from a previous session
lobster command "pipeline export" --session-id liver_study

# Export from the most recent session
lobster command "pipeline export" --session-id latest

This is especially useful for:

• Multi-day analyses: Run QC on Day 1, export the notebook on Day 2
• Scripted pipelines: Automate analysis then export in a CI job
• Sharing workflows: Hand off a session name to a colleague for notebook generation

When to Use --session-id

Tip: Without --session-id after a terminal restart, pipeline export will display a guidance message explaining how to load a previous session.

For workflow examples using session continuity, see Data Analysis Workflows.

Configuration

/modes

List available operation modes with descriptions.

/modes

Available Modes:

• development: Claude 4.5 Sonnet supervisor, Claude 3.7 Sonnet workers - fast development with balanced performance
• production: Claude 4.5 Sonnet for all agents - production-ready quality across all agents

/mode <name>

Change operation mode and agent configurations.

/mode production                   # Switch to production mode (Claude 4.5 Sonnet all agents)
/mode development                  # Use development profile (mixed models for cost efficiency)

Effects:

• Updates all agent model configurations
• Adjusts performance and cost parameters
• Maintains current data and session state

Dashboard and Monitoring

/dashboard

Switch to the interactive Textual-based dashboard.

/dashboard

Launches a full-screen interactive terminal UI with:

• Multi-panel cockpit layout for real-time monitoring
• Live agent activity tracking and handoff visualization
• Query input with streaming responses
• Token usage and system status panels

Press ESC to quit, ^P for command palette.

Note: You can also launch the dashboard directly with lobster dashboard from the command line.

/status-panel

Show comprehensive system health dashboard (Rich panels in terminal).

/status-panel

Includes:

• Core system status
• Resource utilization
• Agent status and health

/workspace-info

Show detailed workspace overview with recent activity.

/workspace-info

Displays:

• Workspace configuration and paths
• Recent files and data access
• Data loading statistics

/analysis-dash

Show analysis monitoring dashboard.

/analysis-dash

Tracks:

• Active analysis operations
• Generated visualizations
• Processing performance metrics

/progress

Show multi-task progress monitor for concurrent operations.

/progress

Displays active background operations with progress bars and status.

Utility Commands

/clear

Clear the terminal screen.

/clear

/exit

Exit Lobster AI (with confirmation prompt).

/exit

Shell Integration

Lobster AI supports common shell commands directly without the / prefix:

Directory Navigation

cd /path/to/data                  # Change directory
pwd                               # Print working directory
ls                                # List directory contents with metadata
ls /path/to/folder               # List specific directory

File Operations

mkdir new_folder                  # Create directory
touch new_file.txt               # Create file
cp source.txt dest.txt           # Copy file
mv old_name.txt new_name.txt     # Move/rename file
rm unwanted_file.txt             # Remove file

File Viewing

cat data.csv                     # View file with syntax highlighting
open results/                    # Open in file manager (same as /open)

Enhanced Features:

• Syntax Highlighting: Automatic language detection
• Structured Output: Tables and formatted displays
• Rich Metadata: File sizes, modification dates, types

Configuration Commands

Setup Wizard

# Interactive setup — configure provider, API keys, optional dependencies
lobster init

# Reconfigure (creates backup of existing .env)
lobster init --force

# Non-interactive mode (for CI/CD)
lobster init --non-interactive --anthropic-key=sk-ant-xxx

# Include semantic search installation (non-interactive)
lobster init --install-vector-search --anthropic-key=sk-ant-xxx

The --install-vector-search flag (v1.0.7+) installs the vector-search extra for semantic ontology matching (ChromaDB + SapBERT). In interactive mode, lobster init prompts for this after the Docling prompt. See Semantic Search Guide for details.

Agent Configuration

# Display current runtime configuration (shows per-agent models)
lobster config show-config

# Show configuration for specific workspace
lobster config show-config --workspace /path/to/workspace

# Show all agents (including premium-only)
lobster config show-config --show-all

# List available model presets
lobster config list-models

# List available testing profiles
lobster config list-profiles

# Test current provider connectivity (auto-detects provider)
lobster config test

# Test specific configuration profile
lobster config test --profile production

# Test specific agent in a profile
lobster config test --profile production --agent transcriptomics_expert

# Create custom configuration interactively
lobster config create-custom

# Generate environment template
lobster config generate-env

Note: As of v0.4.0, lobster config show-config displays actual runtime configuration from ConfigResolver and ProviderRegistry, showing which provider and model each agent is using. This works with all six providers: Anthropic, Bedrock, Ollama, Gemini, OpenAI, and Azure AI.

Usage Examples

Common Workflows

Starting a New Analysis

# Start Lobster
lobster chat

# Check existing workspace
/workspace list

# Load previous work by index (v0.2+)
/workspace load 1

# Or restore recent session
/restore recent

# Or load new data
/read my_data.h5ad

# Check data status
/data

# Begin analysis
"Analyze this single-cell RNA-seq data and identify cell types"

Dataset Browsing and Selection (v0.2+)

# List all datasets with numbered index
/workspace list

# Get detailed info for first dataset
/workspace info 1

# Load that dataset by index
/workspace load 1

# Or get info about specific pattern
/workspace info *liver*

# Check full details before loading
/workspace info geo_gse12345

# Load by pattern
/workspace load *clustered*

Data Exploration

# Quick data overview
/data

# View metadata
/metadata

# Check file structure
/tree

# Explore analysis options
"What analysis can I do with this data?"

Visualization Management

# List all plots
/plots

# Open specific plot
/plot plot_3

# Open plots folder
/plot

# Save current state
/save

Session Management

# Check system status
/status

# View workspace info
/workspace

# Export everything
/export

# Clean restart if needed
/reset

Advanced Usage

Batch Operations

# Load multiple files
/read *.h5ad

# Pattern-based restoration
/restore *experiment_2*

# Dataset loading operations
/restore batch_*

Configuration Switching

# Check available modes
/modes

# Switch for production analysis
/mode production

# Verify change
/status

Debugging and Monitoring

# Start with verbose debugging
lobster chat --verbose --debug

# Monitor system resources
/dashboard

# Track analysis progress
/progress

# View detailed workspace info
/workspace-info

Troubleshooting Commands

Diagnostic Information

# System status
/status

# Input capabilities
/input-features

# Workspace health
/workspace

# Data validation
/metadata

Recovery Operations

# List available data
/workspace list

# Restore from backup
/restore all

# Clear and restart
/reset

# Export before major changes
/export

Performance Optimization

# Check resource usage
/dashboard

# Switch to development mode for lighter resource usage
/mode development

# Monitor active operations
/progress

This comprehensive CLI reference covers all available commands and their usage patterns. For analysis-specific workflows, see the Data Analysis Workflows guide. For cross-session pipeline export examples, see the Session Continuity section above.