7. Starting omicOS: cli mode (terminal)
This chapter covers pure-terminal usage. omicos cli combines the daemon and the chat interface into one, opening a full-screen chat window directly in your terminal, with no browser required at all. This is the preferred choice for SSH / HPC environments.
7.1 One Command Does It All
cd ~/my-analysis
omicos cli
Expected output: the terminal switches to a full-screen chat interface (no more regular scrolling output). The current process and session appear at the top, with an input box at the bottom. Press Ctrl+C to quit; the terminal returns to normal.
What it does: starts a local daemon → registers it as a process with a (cli) suffix → enters the chat interface. omicos cli is equivalent to omicos cli chat — chat is the default subcommand.
7.2 Chat Interface Keybindings
| Key | Action |
|---|---|
| Enter | Send the message (pressing Enter to pick an IME candidate won't accidentally trigger a send) |
| Shift + Enter / Alt + Enter / Ctrl + J | New line (for multi-line messages) |
| ↑ / ↓ | Scroll history when the input box is empty; browse previously sent messages when it has content |
| PageUp / PageDown, Ctrl+U / Ctrl+D | Scroll the conversation |
| Esc | Close the current popup (slash-command list, @-mention picker, etc.) |
| Ctrl + C | Interrupts the current turn if a task is running; quits when idle |
7.3 Automatically Attaches When a serve Instance Is Already Running
If a omicos serve instance is already running in this workspace, omicos cli doesn't error out or start a second daemon — it connects directly to that one and opens the chat interface. In that case the session history you see in the terminal and on the web app is the same data, because it's the same process.
Only when there's no daemon running in the workspace does omicos cli start its own — and only then does it take on the standalone (cli) identity described in 7.4 below.
To connect to an omicos that isn't in the current workspace but whose address you know, use --attach:
omicos cli --attach http://127.0.0.1:5055
Expected output: goes straight into the chat interface. If that omicos's workspace doesn't match your current directory, a line is printed first:
[omicos] attaching explicitly to Core workspace /Users/you/other-project; CLI started in /Users/you/my-analysis
7.4 Differences from serve When cli Starts Its Own Daemon
When omicos cli starts its own daemon, the flags are largely the same as omicos serve, but the defaults differ:
| Dimension | omicos serve |
omicos cli |
|---|---|---|
Default --data-dir |
.omicos |
.omicos/cli |
Default --upstream-base-url |
none | https://auth.omicos.cn (both overridable with OMICOS_UPSTREAM_BASE_URL) |
| Process identifier | local-<workspace_id> |
local-<workspace_id>-cli |
| Process display name | original name | original name + (cli) |
| Logging | --debug true / --log-filter / RUST_LOG |
The UI takes over the screen; only RUST_LOG is available |
Because the data-dir differs, session history is isolated between a cli-started daemon and a serve daemon. In the web process selector, entries with a
(cli)suffix and those without form two separate namespaces. If something you chatted about in cli "shows no history" on the web, you most likely selected the wrong process.
7.5 cli-Specific Flags
| Flag | What it does |
|---|---|
--attach <URL> |
Connect to an omicos that's already running (see 7.3), instead of starting its own. |
--process <id> |
Asserts that this machine's running omicos process id matches — errors out if it doesn't. Used in scripts to guard against attaching to the wrong instance. |
--session <id> |
Resume a specific session (defaults to the most recently active one). |
--new |
Force-start a new session. |
--process is often mistaken for "connect to some cloud process on a remote machine" — it isn't that. It only verifies this machine's running omicos identity, and errors out immediately if it doesn't match:
omicos cli --process local-deadbeef
Expected output:
Error: --process local-deadbeef does not identify the running local Core (local-9f2c4d7a1b8e4f5c8d3a6b0e2f7c1a94); use the web app for another process or omit --process
To operate an omicOS instance on another machine, use the web app, or set up port forwarding per the remote deployment recipes and run omicos cli on that machine.
7.6 Login / Logout
Device-code login and logout in cli mode:
omicos cli login
omicos cli logout
See Chapter 5 for the output.
7.7 Debug Logs
--debug / --log-filter aren't usable while the chat interface occupies the screen. To view logs, you can only use an environment variable:
RUST_LOG=omicos_core=debug omicos cli
Expected output: the chat interface opens as usual, and debug logs go to stderr. To keep them, redirect stderr to a file:
RUST_LOG=omicos_core=debug omicos cli 2> omicos-cli.log
Expected output: the chat interface opens as usual, and logs go into omicos-cli.log; run tail omicos-cli.log after quitting to view it.
Next Steps
- Want to run your analysis on a remote server? → Chapter 8: Remote / SSH / HPC Deployment
- Want to look up all command flags? → Chapter 9: Command & Flag Reference