9. Command & Flag Reference
This chapter is a pure reference — every omicos command and flag gathered into tables for quick lookup. Baseline version 0.3.29.
9.1 Command Tree
omicos
├── serve HTTP daemon + browser UI (the default when no subcommand is given)
├── cli terminal chat interface + embedded daemon
│ ├── chat interactive chat (cli's default subcommand)
│ ├── login device-code pairing login
│ └── logout log out the account saved by cli
├── login email / password login (terminal, no browser needed)
├── env
│ ├── setup install / repair the Python analysis environment
│ ├── doctor diagnose Python and kernel availability
│ └── list list candidate Python environments as JSON
├── hpc interactive environment wizard for servers / HPC, then serve
├── a2a Agent2Agent endpoint (available in releases after 0.3.29)
│ ├── enable / disable turn the endpoint on / off
│ ├── status report whether the endpoint will mount, and why not if it won't
│ └── key
│ ├── create issue an API key (shown only this once)
│ ├── list list issued keys (id and label only)
│ └── revoke <id> revoke a key, effective on the next request
└── recover-conversations attribute pre-isolation legacy sessions to the current account (operator use)
View this list:
omicos --help
Expected output (excerpt):
Rust runtime core for OmicOS
Usage: omicos [OPTIONS] [COMMAND]
Commands:
login
serve
cli Terminal chat client (TUI) — talks to a running omicos process over HTTP+SSE. See `omicos cli --help`
env Manage the bundled Python analysis environment (the shared kernel)
a2a Manage the Agent2Agent (A2A) endpoint: on/off, API keys, status
hpc Guided setup for servers / HPC: choose (or install) a Python env for the kernel, optionally make it the default, then serve. Interactive
recover-conversations Attribute quarantined pre-isolation conversations after the operator has verified that this account exclusively owns the local data root
help Print this message or the help of the given subcommand(s)
Options:
--host <HOST> [default: 127.0.0.1]
--port <PORT> [default: 5055]
…
-h, --help Print help
-V, --version Print version
Check the version:
omicos --version
Expected output:
omicos 0.3.29+a1b2c3d
9.2 serve Flags
The top-level omicos (with no subcommand) accepts this same set of flags.
| Flag | Type | Default | Description |
|---|---|---|---|
--host |
string | 127.0.0.1 |
Bind address |
--port |
u16 | 5055 |
HTTP port; automatically moves forward up to 100 ports when taken |
--data-dir |
path | .omicos |
Workspace data directory |
--upstream-base-url |
string | none | Fallback target for the local /api/* proxy; env OMICOS_UPSTREAM_BASE_URL. Doesn't determine kernel location, and isn't the switch for cloud access |
--kernel-base-url |
string | none | Remote kernel address; env OMICOS_KERNEL_BASE_URL; setting it skips local Python environment bootstrap |
--no-browser |
flag | off (browser opens by default) | Don't open the browser automatically (bare flag) |
--debug |
bool (with value) | false |
Debug logging; must be written as --debug true, not a bare flag |
--log-filter |
string | none | Log filter expression; env OMICOS_LOG_FILTER |
--report-port |
flag | off | Prints an extra line, OMICOS_LISTENING_PORT=<port>, once bound, for scripts to read the actual port |
9.3 cli Flags
Daemon flags:
| Flag | cli default | Description |
|---|---|---|
--attach <URL> |
none | Connect to an omicos that's already running, instead of starting its own |
--host |
127.0.0.1 |
Same as serve |
--port |
5055 |
Same as serve |
--data-dir |
.omicos/cli |
serve uses .omicos |
--upstream-base-url |
https://auth.omicos.cn |
serve has no default; both overridable with OMICOS_UPSTREAM_BASE_URL |
In cli mode the UI takes over the screen, so
--debug/--log-filterare unavailable — only theRUST_LOGenvironment variable works.
Chat flags:
| Flag | Type | Description |
|---|---|---|
--process |
string | Asserts this machine's omicos process id; errors out immediately if it doesn't match. Not for connecting to a remote process |
--session |
string | Resume a specific session (defaults to the most recently active one) |
--new |
flag | Force a new session (mutually exclusive with --session) |
Subcommands: omicos cli chat (default), omicos cli login, omicos cli logout.
9.4 login Flags
| Flag | Default | Description |
|---|---|---|
--server |
https://auth.omicos.cn |
Auth service address |
--email |
(interactive prompt) | |
--password |
(interactive prompt) | Password |
--name |
(taken from the conda env name or directory name) | Process display name |
--force |
off | Force re-authentication even if already logged in |
--status |
off | Only check login status, print it, and exit |
--logout |
off | Log out and delete credentials |
9.5 cli login Flags
| Flag | Default | Description |
|---|---|---|
--server |
https://auth.omicos.cn |
Auth service address (device-code flow only) |
--logout |
off | Log out (equivalent to omicos cli logout) |
9.6 env Flags
| Subcommand | Flag | Description | |||
|---|---|---|---|---|---|
env setup |
--force |
Re-run uv sync even if the environment already exists |
|||
env setup |
--yes |
Non-interactive, auto-confirm | |||
env setup |
`--index <auto\ | pypi\ | aliyun\ | tuna>` | Package index; defaults to auto (probes for the fastest one) |
env setup |
--index-url <URL> |
Specify an index URL directly; takes precedence over --index and UV_INDEX_URL |
|||
env doctor |
(no flags) | Diagnose and print environment information | |||
env list |
--json |
Output candidate environments as JSON (on by default, and currently the only format) |
9.7 hpc Flags
omicos hpc accepts every serve flag (applied as-is once the environment is chosen), plus:
| Flag | Description |
|---|---|
--reselect |
Re-run the selection flow even if OMICOS_KERNEL_PYTHON is pinned or a default environment was already saved |
9.8 a2a Flags (available in releases after 0.3.29)
The Agent2Agent endpoint lets external agents call this omicos over the A2A protocol. Requires pro tier or above; for the full protocol and integration details, see Advanced (3): A2A Protocol & External Agent Interop — this section only lists the commands.
| Command | Flag | Description |
|---|---|---|
a2a enable |
— | Turn the endpoint on, effective on the next serve |
a2a disable |
— | Turn the endpoint off, existing keys are kept |
a2a status |
--host <address> (default 127.0.0.1) |
Reports whether the endpoint will mount for the given bind address, and why not if it won't |
a2a key create |
--label <name> |
Issue a key. Shown in plaintext only this once — only the hash is stored afterward and it can't be recovered |
a2a key list |
— | Lists key id, label, creation time, status (never prints the key itself) |
a2a key revoke <KEY_ID> |
— | Revokes it, effective on the next request, no restart needed |
To debug why the endpoint hasn't come up, use status:
omicos a2a status
Expected output (not yet enabled):
A2A endpoint status
config : /Users/you/.omicos/a2a.json
keys : /Users/you/.omicos/a2a_keys.json
enabled : false
exposed agent: omicverse_omni
plan : pro (A2A requires pro or higher — ok)
active keys : 0
file parts : inline limit 100 MiB; url parts disabled
artifacts : files up to 1024 KiB ship inline; larger ones as /a2a/v1/artifacts URLs
bind host : 127.0.0.1 (loopback)
endpoint : NOT mounted — disabled. Enable with `omicos a2a enable`.
discovery : /.well-known/agent-card.json (always anonymous)
9.9 recover-conversations Flags
Claims legacy sessions left over from before "account isolation" shipped, attributing ownerless ones to the currently logged-in account. Rarely needed day to day — only when upgrading from a very old version and finding legacy sessions missing.
| Flag | Description |
|---|---|
--dry-run |
Only reports how many sessions are recoverable, without changing any ownership |
--expected-count <N> |
The number of non-empty sessions you expect to recover; required for a real run, mutually exclusive with --dry-run |
--confirm-exclusive-data-root |
Confirms this data directory has never been shared with anyone else / another account. Required for a real run |
Dry run first:
omicos recover-conversations --dry-run
Expected output:
Recovery preview: 12 recoverable non-empty conversations (9 ownerless, 3 current OS-user anonymous); 0 conflicting ownership rows. No files changed.
Once the numbers check out, run it for real:
omicos recover-conversations --expected-count 12 --confirm-exclusive-data-root
Expected output:
Recovered 12 conversations locally; cloud upload remains disabled until each conversation is explicitly continued or deleted.
9.10 serve vs cli Default Comparison
| Dimension | serve |
cli |
|---|---|---|
--data-dir |
.omicos |
.omicos/cli |
--upstream-base-url |
no default | https://auth.omicos.cn |
| Logging method | --debug true / --log-filter / RUST_LOG |
RUST_LOG only |
| Process identifier | local-<workspace_id> |
local-<workspace_id>-cli |
| Interface | browser web app + terminal dashboard | terminal chat interface |
These defaults only apply when cli starts its own daemon. When a serve instance is already running in the workspace,
omicos cliconnects directly to it and uses serve's data directory and process identity.Nearly every flag has a corresponding environment variable that can override it; for the full list, see Chapter 10: Environment Variable Reference.