CLI Commands

The Omnodex CLI installs hooks, runs detection and reports, starts the local dashboard, and manages the cloud connection and MCP proxy.

Usage

omnodex <command> [options]

Run commands on the host where the agent runs. If omnodex is not on your PATH, use node <repo>/packages/cli/dist/index.js instead. See Installation.

Commands

`install`

Install Omnodex hooks for an agent into a project.

omnodex install <target> [project]

Target	What it writes
`claude-code`	Hook entries in `.claude/settings.local.json`
`codex`	Hook entries in `.codex/hooks.json`
`antigravity`	Hook entries in `.agents/hooks.json`, and optionally the MCP proxy in `.agents/mcp_config.json`

Flag	Description
`--debug`	Enable verbose hook logging
`--project-settings`	(claude-code) Write to `.claude/settings.json` instead of `settings.local.json`
`--hooks`	(antigravity) Install hooks only
`--mcp`	(antigravity) Install the MCP proxy only. Combine `--hooks --mcp` for both. With neither flag, installs hooks only.
`--legacy-shim`	Write absolute handler paths into the hooks instead of using the stable launchers in `~/.omnodex/bin/`. Not recommended.

If project is omitted, the current directory is used.

install codex installs hooks only; it does not register the Omnodex MCP server with Codex. See the Codex guide.

After installing, the command connects this host to the hosted dashboard: if no API token exists it starts the device code flow (press Ctrl+C to skip), and if one exists it prints a connection link.

`uninstall`

Remove Omnodex hooks from a project.

omnodex uninstall [target] [project] --confirm

If target is omitted, removes all Omnodex hooks found in the project. --confirm is required. Event data is not affected.

`status`

Show which Omnodex hooks are installed in a project.

omnodex status [project] [--all]

Flag	Description
`--all`	List every project where hooks were installed, with warnings for stale installs

On a host connected to a hosted dashboard, status also reports the last automatic sync and any error it recorded. Background syncs stay silent so they never interrupt an agent, so this is where a sync that has been failing shows up.

`connect`

Connect this host to your hosted dashboard account.

omnodex connect [--token <omx_...>] [--platform <name>]

Flag	Description
`--token`	Store this API token instead of running the device code flow
`--passphrase`	Use this sync passphrase instead of the stored or generated one
`--platform`	Platform identifier sent with the connection, for example `codex`
`--api`	API endpoint, for self-hosted instances

Without an API token, connect starts a device code flow: it shows a short code and a URL. Open the URL, sign in or create an account, and enter the code; the CLI receives the token automatically. With a token already stored, it prints a one-time connection link to open while signed in.

On first run it generates a sync passphrase (six random words). The token and passphrase are saved to stream-config.json in your Omnodex home. The passphrase is transferred end-to-end encrypted: the decryption key travels in the URL fragment, which is never sent to the server.

The MCP proxy’s omnodex_connect tool runs the same flow from inside an agent.

`sync`

Encrypt the local read model and upload it to the hosted dashboard.

omnodex sync [--token <omx_...>] [--passphrase <phrase>]

Credentials come from flags, then OMNODEX_API_TOKEN and OMNODEX_SYNC_PASSPHRASE, then stream-config.json. Requires the Hosted tier or above. Each host uploads under its own machine ID, derived from the hostname; set machine.label in config.json for a readable name.

A connected host does this on its own when a session ends, and every 15 minutes while an MCP proxy session runs, so this command is mostly for forcing a sync now. See Automatic sync.

For real-time streaming instead of periodic uploads, run omnodex dashboard on a connected host.

`dashboard`

Start the local web dashboard.

omnodex dashboard [port] [--roots <path> ...] [--no-detect]

Option	Default	Description
`[port]`	`7890`	Port for the dashboard web server
`--roots`	(none)	Additional Omnodex home directories to read, space-separated. The dashboard’s own home is always included.
`--no-detect`	(off)	Skip the detection pass over existing events on startup

The dashboard replays events from every root, runs detection, and pushes new events and findings to the browser in real time. On a host connected with omnodex connect and a tier that includes live streaming, it also encrypts new events and streams them to the hosted dashboard. See Using the Dashboard.

`detect`

Scan the event log for risks and record findings.

omnodex detect [session]

Scans all sessions, or only the given session ID. Detection is idempotent: running it again on the same events produces the same findings.

`report`

Print a text summary of sessions and findings.

omnodex report

`replay`

Rebuild the SQLite read model (traces.db) from the event log.

omnodex replay

Useful if the database is damaged or you want to re-apply updated rules to past events.

`clear`

Delete event data.

omnodex clear <session-id>       # remove one session
omnodex clear --all --confirm    # delete the entire Omnodex home

Hooks already written into projects are not removed; use uninstall for those.

`spike`

Generate a simulated session to check that the pipeline works.

omnodex spike [name]

If name is given, the session ID is sess_<name>. Otherwise a unique ID is generated.

`mcp-proxy`

Manage the MCP proxy.

omnodex mcp-proxy <start|install|status>

Subcommand	Description
`start [--config <path>]`	Start the proxy on stdin/stdout. Uses `omnodex-proxy.json` in the Omnodex home if `--config` is omitted.
`install`	Create a template `omnodex-proxy.json` if none exists
`status`	Show the configured upstream servers and redaction settings

See MCP proxy configuration.

`update`

Update a source or npm install.

omnodex update [--check] [--refresh-launchers]

Flag	Description
`--check`	Show available updates without installing
`--refresh-launchers`	Rewrite the hook launchers in `~/.omnodex/bin/` without updating

For a source install, runs git pull --ff-only, npm install, and npm run build in the clone, and warns first if it has uncommitted changes. For an npm install, runs npm update -g omnodex. A background check (cached for 24 hours) prints a one-line notice when an update is available.

`--version`

omnodex --version
omnodex -V

A source install prints the branch and commit, for example 0.0.0 (source: main @ a881f59), with + after the hash if the checkout has local changes. An npm install prints the package version.

`license`

Show the current license tier and features.

omnodex license
omnodex license clear    # remove the cached license

Environment variables

Variable	Default	Description
`OMNODEX_HOME`	`~/.omnodex`	Omnodex home directory
`OMNODEX_API_TOKEN`	(none)	API token for cloud features. Overrides `stream-config.json`.
`OMNODEX_SYNC_PASSPHRASE`	(none)	Sync passphrase. Overrides `stream-config.json`.
`OMNODEX_AUTO_SYNC`	(unset)	Set to `0` to turn automatic sync off on this host
`OMNODEX_DEBUG`	(unset)	Set to `1` for detailed launcher logging
`OMNODEX_NO_UPDATE_CHECK`	(unset)	Set to `1` to disable the background update check

Next steps

Configuration - Configuration files
Quick Start - Get started