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 installedomics-os --versionomics-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 --helpA 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 --helpomics-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 keyFor 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 --jsonThe older name OMICSOS_API_KEY still works in omics-os, but it is never passed to a local Lobster AI engine.
| Command | What it does |
|---|---|
omics-os status | Who 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 logout | Sign 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 .responseIn 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 slidedeckomics-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 uninstallomics-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.4 | omics-os |
|---|---|
lobster cloud login / logout / status / profiles / use | omics-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.