CLI Commands

The Omnodex CLI is the primary interface for running tracing, detection, and reporting.

Usage

omnodex <command> [options]

If you installed from source instead of npm, use npx omnodex in place of omnodex.

Commands

install

Install the Omnodex hook into an agent runtime.

omnodex install <target> [project]

Target	Description
claude-code	Install as a Claude Code hook
codex	Install as an OpenAI Codex hook
antigravity	Install as a Google Antigravity hook

Flag	Description
--debug	Enable verbose shim logging
--project-settings	(claude-code only) Write to settings.json instead of settings.local.json
--hooks	(antigravity) Install hooks only
--mcp	(antigravity) Install MCP proxy only. Combine --hooks --mcp for both. Default (no flags): hooks only
--legacy-shim	Use absolute-path shims instead of stable launchers. Stable launchers (the default) survive npm updates and Node version switches without reinstalling hooks.

If project is omitted, defaults to the current working directory.

uninstall

Remove Omnodex hooks from a project.

omnodex uninstall [target] [project] --confirm

If target is omitted, removes all hooks found in the project. The --confirm flag is required to prevent accidental removal.

status

Show current Omnodex status: which hooks are installed, event count, last activity.

omnodex status [project] [--all]

Flag	Description
--all	Show full installation registry across all projects, with stale install warnings

update

Check for and install updates. Works for both npm and source installs.

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

Flag	Description
--check	Dry run: show available updates without installing
--refresh-launchers	Rewrite stable launchers without checking for updates

For npm installs, this runs npm update -g omnodex. For source installs, it runs git pull --ff-only, npm install, and npm run build. If you have uncommitted changes in a source install, the command warns you before proceeding.

A background update check runs automatically on each CLI invocation (except update itself). If an update is available, a one-liner notification appears on the next invocation. The check is cached for 24 hours and is fully non-blocking.

--version

Show the installed Omnodex version.

omnodex --version
omnodex -V

For npm installs, this prints the semver version (e.g. 1.2.3). For source installs, it includes the git branch and commit: 0.0.0 (source: main @ a881f59). A + suffix on the commit hash indicates uncommitted changes.

detect

Run risk detection on all unanalyzed events.

omnodex detect [session]

If a session ID is provided, only that session is scanned. Otherwise all sessions are scanned. Detection is idempotent - running it multiple times on the same events produces identical results.

dashboard

Start the local web dashboard with real-time updates.

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

Option	Default	Description
[port]	7890	Port for the dashboard web server
--roots	(none)	Additional OMNODEX_HOME roots to tail. Space-separated paths. The default root is always included.
--no-detect	(off)	Skip the historical detection pass on startup

The dashboard automatically runs detection, replays events from all configured roots, and opens an SSE connection for live updates. See Using the Dashboard for multi-source aggregation details.

Cloud streaming: When OMNODEX_API_TOKEN and OMNODEX_SYNC_PASSPHRASE are set and your tier includes live streaming, the CLI automatically encrypts and pushes events to the hosted dashboard at dashboard.omnodex.com in real time. Sign in to the dashboard with your email and password to view events - your passphrase is encrypted under your account credentials using zero-knowledge key wrapping, so the dashboard can decrypt without re-entering it each session.

report

Generate a text-based summary report of findings.

omnodex report

replay

Replay the event log to rebuild the read model (SQLite database).

omnodex replay

Useful if the database becomes corrupted or you want to apply updated rules to historical events.

clear

Delete all event log data and the read model.

omnodex clear --all --confirm

The --confirm flag is required to prevent accidental data loss. This permanently deletes events.jsonl, omnodex.db, and related data under OMNODEX_HOME. Hook installations are not affected - use uninstall for that.

spike

Run a mock pipeline that generates sample events for testing. Useful for verifying your installation works.

omnodex spike [name]

If name is provided, the session ID is set to sess_<name>. Otherwise a unique timestamp-based ID is generated.

sync

Encrypt the local read model and push it to the cloud.

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

Flag	Description
--token	API token (overrides OMNODEX_API_TOKEN env var)
--passphrase	Encryption passphrase (overrides OMNODEX_SYNC_PASSPHRASE env var)

Requires a tier that includes encrypted sync (Hosted or above). The command rebuilds the read model, encrypts it with your passphrase, and uploads the encrypted blob to the Omnodex cloud. Each machine gets its own blob, identified by a stable machine ID derived from the hostname.

Run this periodically or after significant agent activity to keep the hosted dashboard up to date. For real-time streaming, use omnodex dashboard with the same credentials set - it streams events as they arrive.

connect

Generate a secure connection link to link this machine to your dashboard account.

omnodex connect [--platform <name>] [--label <name>]

Flag	Description
--platform	Platform identifier included in the connection (e.g. claude-code, codex)
--label	Human-readable label for this machine (overrides config file label for this connection)

On first run, connect auto-generates a sync passphrase (six random words) and saves it to ~/.omnodex/stream-config.json. Subsequent runs reuse the existing passphrase.

The command prints a one-time connection link. Open it in your browser while signed in to your dashboard account. The passphrase is transferred end-to-end encrypted: the decryption key is carried in the URL fragment (never sent to the server). The link expires after 15 minutes.

After connecting, the dashboard can decrypt events pushed from this machine. You can also connect via plugin tools (omnodex_connect in the MCP proxy) without needing the CLI on PATH.

license

Show current license tier and features.

omnodex license

Use omnodex license clear to remove the cached license.

mcp-proxy

Manage the MCP proxy interceptor.

omnodex mcp-proxy <subcommand>

Run omnodex mcp-proxy help for subcommand details.

Environment Variables

Variable	Default	Description
OMNODEX_HOME	~/.omnodex	Directory for event logs, database, and config
OMNODEX_API_TOKEN	(none)	API token for cloud features (provided at account registration or data stream creation)
OMNODEX_SYNC_PASSPHRASE	(none)	Passphrase for zero-knowledge encryption of cloud sync and live streaming. Auto-generated by omnodex connect, or you can set it manually. Stored encrypted in your account via key wrapping.

Next Steps

• Configuration - Configuration file options
• Quick Start - Get started with the CLI