Omics-OSDocs
CloudUser Guide

Omics-OS CLI

The omics-os terminal client for Omics-OS Cloud: install, log in (browser, device, tenant, API key), chat and query, sessions, files, projects, upload, BioVault, editor, doctor, upgrade and uninstall, and how to move from @omicsos/lobster 0.4.

omics-os is the terminal client for Omics-OS Cloud. It is the npm package omics-os 1.3, the new name of @omicsos/lobster 0.4. One command, omics-os, is organised by surface: lobster, biovault, editor, app and playground, plus account and installation commands.

The agents run on Omics-OS Cloud, not on your machine. The client contains no analysis engine. To analyse data on your own machine, install Lobster AI, the open-source Python engine, which has its own lobster command: see Installation.

Install

Requires Node.js 22 or later. If @omicsos/lobster 0.4 is installed, uninstall it first: both packages install the lobster-cli command.

npm uninstall -g @omicsos/lobster   # only if 0.4 is installed
npm install -g omics-os
omics-os --version
omics-os 1.3.0 (Omics-OS Cloud client)

On Windows, omics-os runs in Command Prompt and PowerShell. If PowerShell refuses to run omics-os because of its execution policy, run omics-os.cmd with the same arguments. omics-os biovault run download is supported on macOS and Linux; on Windows, use WSL.

First look

Bare omics-os prints a short status banner and exits 0. It says whether you are signed in and what to try next. It does not print the full help; omics-os --help does, grouped by Get started, Omics-OS Cloud, Account and This installation.

omics-os 1.3.0  Omics-OS Cloud from your terminal

  ✗ Not signed in.  Start with:  omics-os login

Then
  $ omics-os lobster chat   # chat with Lobster AI
  $ omics-os lobster session list   # your sessions
  $ omics-os doctor   # check this installation

All commands: omics-os --help

A command that does not exist is a usage error with a suggestion, and exit 2:

✗ Unknown command: omics-os loign
Did you mean 'login'?
Run: omics-os --help

omics-os <surface> --help lists the commands of one surface, for example omics-os lobster --help.

Log in

omics-os login                  # opens your browser
omics-os login --device         # no browser on this machine (SSH): prints a URL and a code
omics-os login --tenant acme    # sign in to an organisation's subdomain
omics-os login --api-key <key>  # an API key

For scripts and CI, prefer the environment variable to --api-key, so the key does not land in your shell history:

export OMICS_OS_API_KEY=omk_your_key_here
omics-os lobster session list --json

The older name OMICSOS_API_KEY still works in omics-os, but it is never passed to a local Lobster AI engine.

CommandWhat it does
omics-os statusWho you are signed in as, plan and usage
omics-os profiles list / profiles remove <name>List or remove credential profiles (one per tenant)
omics-os use <name>Switch the active profile
omics-os logoutSign out of this computer

Global options, accepted by every command: --json (machine-readable output on stdout), --profile <name>, --endpoint <url> (API base URL including /api/v1), --no-color (also NO_COLOR=1), --verbose and -V, --version.

Chat and query

omics-os lobster chat                        # a new interactive session
omics-os lobster chat --session-id latest    # pick up your most recent session
omics-os lobster chat --project-id <id>      # file the new session under a project
omics-os lobster query "Find GEO scRNA-seq datasets of human liver fibrosis"
omics-os lobster query -s latest "Plot the UMAP coloured by donor"
omics-os lobster query --json "Summarise session QC" | jq -r .response

In the chat, press Ctrl+C twice to cancel a running reply; /exit, or Ctrl+C when idle, quits. query takes --stream to print text as it arrives and -p, --project-id <id> to associate the session with a project.

Sessions, files and exports

omics-os lobster session list
omics-os lobster session info <id>
omics-os lobster session create --project <project-id> --name "liver study"
omics-os lobster session messages <id>
omics-os lobster session provenance <id>
omics-os lobster session cancel <id>

session also has archive, unarchive, extend (reset the inactivity timeout), share and delete (--force skips the confirmation). With --project, an organisation project's files are copied into the new session.

omics-os lobster files list <session-id>
omics-os lobster files upload <session-id> counts.h5ad
omics-os lobster files download <session-id> <key> [dest]
omics-os lobster files load <session-id> <path>
omics-os lobster files delete <session-id> <key>
omics-os lobster export <session-id> --type report   # report, pipeline or slidedeck

omics-os lobster vector search "<query>" searches ontology terms (cell types, tissues, diseases). omics-os lobster agents list and agents info <name> show the agents in the Omics-OS Cloud catalogue; agents download <name> downloads an agent bundle.

Cloud projects

omics-os lobster projects list
omics-os lobster projects info <project-id>
omics-os lobster projects create <name> [--description <text>]
omics-os lobster projects download <project-id> [folder] [--data] [--dry-run]

create makes a project in your organisation when you logged in with --tenant, otherwise a personal project; the command says which. In an organisation, projects list shows the projects you created. For a project an administrator assigned to you, use the project id they send you; upload --project <id> works for it.

download is a one-way copy of a project's session files into <folder>/sessions/<session-id>/. Nothing is tracked or synced back, and a file already in the folder is skipped, never overwritten. By default only the light files come: notebooks, reports, result tables and plots. Data files such as .h5ad, .h5mu, .fastq and .bam, and any file over 50 MiB, are listed with their sizes and come only with --data. --dry-run shows what a download would bring and writes nothing.

omics-os lobster projects works on your projects in Omics-OS Cloud, which have an id. It is separate from lobster projects in the Lobster AI engine, which works on folders on your machine, and omics-os lobster projects delete does not exist: it points you to the engine's lobster projects delete.

Upload

omics-os upload sends files and whole folders into a project's data on Omics-OS Cloud, straight to storage, in parts, each at its path. It is made for large instrument output and for connections that drop. It works only for organisations that have uploads enabled.

omics-os upload ./run1 --project <project-id>
omics-os upload ./run1 --project <project-id> --include "*.pod5" --dry-run
omics-os --json upload a.pod5 b.pod5 --project <project-id>

If it stops, run the same command again: finished files are skipped and a partly sent file resumes from its last finished part, for 7 days from the start of its upload. A different file at the same path is not overwritten unless you add --replace (the old version is kept for 30 days). --concurrency <n> sets the parts sent at once (1 to 16, default 4). A file can be up to 48.8 TiB, within your organisation's per-file limit. Empty files and links are skipped and listed. To delete files from a project, use the web app.

BioVault and the editor

omics-os biovault works on BioVault drafts and runs: draft (new, create, list, show, export, apply, edit, literature, discard), run (show, prompt, samples, problems, decisions, package, download, start, recover, cancel), runs and features. Creating or editing a draft is not approval to start it: run start starts a billable run and needs --review and --yes. run download checks each file against the folder's SHA-256 manifest. See BioVault.

omics-os editor works on the LaTeX editor: generate, compile, files, pull, push, meta and download, each with a session id. omics-os app and omics-os playground print the address of the Omics-OS Cloud workspace and the Agent Playground.

Check, upgrade and remove

omics-os doctor              # version, login, Lobster AI engines and shortcuts
omics-os upgrade --dry-run   # print the command without running it
omics-os upgrade
omics-os uninstall --dry-run # list every path and command; change nothing
omics-os uninstall

omics-os uninstall signs out first, then removes this client's sign-in, profiles, config and shortcuts, then the npm package. It never touches the Lobster AI engine (~/.lobster, ~/.config/lobster, workspaces); lobster purge removes those. --keep-credentials keeps your sign-in and profiles, and --yes skips the confirmation (needed when not on a terminal).

omics-os setup writes optional shortcuts (lobster, biovault, editor, app, playground), each of which runs omics-os <surface>. omics-os skills list and omics-os skills install copy the omics-os skills into the agent tools it detects, such as Claude Code, Codex and Cursor.

Moving from @omicsos/lobster 0.4

0.4omics-os
lobster cloud login / logout / status / profiles / useomics-os login / logout / status / profiles / use
lobster cloud query … / chat …omics-os lobster query … / chat …
lobster cloud session … / files … / export … / agents … / vector …omics-os lobster session … / files … / export … / agents … / vector …
lobster cloud vault …omics-os biovault …
lobster cloud editor …omics-os editor …

omics-os also installs lobster-cli, which also accepts the 0.4 grammar (lobster-cli cloud login, lobster-cli cloud chat). The page Cloud CLI 0.4 describes that grammar.

On this page