Cloud CLI

Install and use the Omics-OS Cloud CLI (@omicsos/lobster) to access cloud agents, sessions, files, and vector search from your terminal — no Python required.

The Omics-OS Cloud CLI is a standalone Node.js terminal client that connects directly to Omics-OS Cloud. Agents run server-side — no Python, no local GPU.

Python vs npm: The Python package (lobster-ai) runs AI agents locally with your own LLM keys. The npm package (@omicsos/lobster) connects to Omics-OS Cloud. These are separate tools with separate credential systems.

Installation

npm install -g @omicsos/lobster

Requirements: Node.js >= 22

Verify:

lobster --version

Quick Start

lobster init          # Interactive setup wizard
lobster cloud login   # Authenticate via browser
lobster cloud chat    # Start chatting with cloud agents

Authentication

lobster cloud login

Opens your browser for Omics-OS login. The browser completes Omics-OS login and returns only a one-time handoff code to the local callback. The CLI exchanges that material with Omics-OS for first-party CLI credentials.

API Key (CI / Headless)

For CI pipelines and automation, use an API key with the omk_ prefix:

lobster cloud login --api-key omk_your_key_here

Or via environment variable (preferred — avoids shell history exposure):

OMICSOS_API_KEY=omk_live_abc123def456 lobster cloud chat

For browserless or SSH environments, use device login which displays a URL and code to authorize from any browser:

lobster cloud login --device

The CLI prints a URL and a short code. Open the URL on any device with a browser, enter the code, and complete authentication. The CLI receives credentials once approved.

Logout

lobster cloud logout

Logout revokes CLI credentials server-side and removes local credential material.

Credential Storage

The npm Cloud CLI stores credentials in ~/.config/omics-os/credentials.json with private file permissions (0600). It does NOT store Cognito refresh tokens.

Endpoint trust: Stored credentials are only attached to trusted Omics-OS and local development origins. For custom endpoints, supply credentials explicitly via --api-key or the OMICSOS_API_KEY environment variable.

Commands

Chat

lobster cloud chat               # Interactive cloud chat
lobster cloud chat --session-id my-study # Resume a specific session

Account and Sessions

lobster cloud status               # Account info + usage
lobster cloud session list         # List your sessions
lobster cloud files list <session> # Files in a session

BioVault (Coming Soon)

BioVault commands are documented ahead of public availability. BioVault itself is not generally accessible yet; join early access before relying on these commands.

# Search for evidence
lobster cloud vault search --genes TP53 --disease "breast cancer" --control healthy

# Submit an analysis job
lobster cloud vault ask --genes BRCA1,BRCA2 --disease "ovarian cancer" --control normal

# List running jobs
lobster cloud vault jobs

Vector Search (Semantic Ontology Matching)

# Semantic search across ontology collections
lobster cloud vector search "glioblastoma"

# With options
lobster cloud vector search "breast cancer" -k 10 -c disease,tissue

Global Options

Flag	Description
`--json`	Output as JSON (for scripting and pipelines)
`--endpoint <url>`	Override API endpoint (credentials not auto-attached; supply explicitly)
`--no-color`	Disable colored output
`--verbose`	Show HTTP request details

Setup Wizard

lobster init

The setup wizard walks through:

Authentication method selection (browser login, device login, or API key)
Credential verification against Omics-OS Cloud
Default preferences (output format, endpoint)

Environment Variables

Variable	Description
`OMICSOS_API_KEY`	API key (`omk_...` format) for non-interactive auth
`OMICSOS_ENDPOINT`	Override default cloud endpoint
`NO_COLOR`	Disable colored output (standard)

Scripting

All commands support --json for machine-readable output:

# Get session list as JSON
lobster cloud session list --json | jq '.[0].id'

# Pipe vault results
lobster cloud vault search --genes TP53 --disease cancer --json > results.json

For CI pipelines, set the OMICSOS_API_KEY environment variable to authenticate without interactive login:

export OMICSOS_API_KEY=omk_ci_your_service_key
lobster cloud session list --json

Installed Binaries

The package installs:

lobster — primary CLI command
lobster-chat — shortcut for cloud chat (Ink TUI)

Troubleshooting

"Node.js version unsupported"

The Cloud CLI requires Node.js 22 or later:

node --version  # Must be >= 22

"Authentication expired"

Re-authenticate with:

lobster cloud logout
lobster cloud login

"Connection refused"

Verify you can reach Omics-OS Cloud:

lobster cloud status --verbose

Check firewall/proxy settings if the request times out.

"Invalid API key"

Ensure your key uses the omk_ prefix and is set correctly:

echo $OMICSOS_API_KEY  # Should start with omk_

Next: Subscription Tiers | Data Formats

Cloud CLI

On this page