7. Starting omicOS: cli mode (terminal)
omicos cli combines the daemon and the chat interface into one: it opens a TUI (text-based interface) chat window directly in your terminal, with no browser required at all. This is the go-to choice for SSH / HPC environments.
7.1 One command does it all
cd ~/your-workspace
omicos cli
It will: automatically start the local daemon → register it as a (cli) process → drop you into the ratatui chat window. omicos cli is equivalent to omicos cli chat; chat is the default subcommand.
7.2 Chat interface keybindings
| Key | Action |
|---|---|
| Enter | Send the message (selecting characters with Enter in an IME won't accidentally trigger a send) |
| Shift + Enter | New line (for writing multi-line messages) |
| Esc | Quit |
7.3 Key differences between cli and serve
omicos cli and omicos serve share the same set of parameters, but their defaults differ — an easy pitfall:
| Aspect | omicos serve |
omicos cli |
|---|---|---|
Default --data-dir |
.omicos |
.omicos/cli |
Default --upstream-base-url |
serve has no default | https://auth.omicos.cn (both can be overridden with the env var OMICOS_UPSTREAM_BASE_URL) |
| Process identifier | local-<workspace_id> |
local-<workspace_id>-cli |
| Process display name | original name | original name + (cli) |
| Logging | supports --debug true / --log-filter |
stdout is taken over by the TUI, so only RUST_LOG works |
Important: Because the data-dir differs, session history in serve mode and cli mode is isolated from each other and does not cross over. 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've most likely selected the wrong process.
7.4 cli-specific parameters (ChatArgs)
Beyond the shared daemon parameters, cli mode has a few chat-specific ones:
| Parameter | Action |
|---|---|
--process <id> |
Connect to a specified cloud relay process instead of the local one. For example, connecting from your laptop to an omicOS process running on a remote HPC node. |
--session <id> |
Resume a specified session (by default, resumes the most recently active session). |
--new |
Force-start a new session. |
--process is a powerful tool for remote use: from your local terminal, you can attach directly to an analysis process on some machine in the cloud and chat with it. See the remote deployment recipes for details.
7.5 Mutually exclusive with serve
omicos cli and omicos serve share the same workspace lock (.omicos/serve.pid), so the two cannot run simultaneously in the same workspace directory. If you need them side by side, give one of them a different --data-dir.
7.6 Debugging logs
In cli mode, stdout is fully occupied by the TUI, so --debug / --log-filter are unavailable. To view logs, you can only use an environment variable:
RUST_LOG=omicos_core=debug omicos cli
Next steps
- Want to run your analysis on a remote server → Chapter 8: Remote / SSH / HPC deployment
- Want to look up all command parameters → Chapter 9: Command and flag reference