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]

Add --help or -h to any command or subcommand to see its usage without running it, for example omnodex sync --help or omnodex mcp-proxy serve -h. Help makes no network calls, writes nothing and skips the update check. A flag a command doesn’t know is rejected before the command does anything.

Run commands on the host where the agent runs. An npm install puts omnodex on your PATH. For a source install that is not on your PATH, use node <repo>/packages/cli/dist/index.js instead. See Installation.

Commands

install

Set up hooks and the Omnodex plugin for your agents.

omnodex install [target] [project]

With no target, finds every supported agent on this host, shows what it will write, and asks once. Targets: claude-code, codex, antigravity (or agy). If project is omitted, the current directory is used. See Installation for what is written where.

Flag	Description
--everywhere	Record every project: hooks go in the agent’s user settings
--this-project	Record only this project: hooks go in the project folder
--yes, -y	Do not ask; records every project unless --this-project is given
--hooks	Install only the hooks
--plugin	Install only the Omnodex plugin
--plugin-version <version>	Install another published plugin version, or latest
--from <file>	Install a plugin file you downloaded
--sha256 <checksum>	With --from, accept a file that is not published if it has this checksum
--no-connect	Skip the hosted dashboard sign-in at the end
--project-settings	(claude-code, this project) Write .claude/settings.json instead of settings.local.json
--mcp	(antigravity) Add the MCP proxy to the project’s .agents/mcp_config.json instead of using the plugin. Combine with --hooks
--debug	Verbose hook logging
--legacy-shim	Write absolute handler paths instead of using the launchers in ~/.omnodex/bin/ (this project only). Not recommended

Without a terminal and without --everywhere or --yes, hooks go into the project. Running install in a project you left out records it again. If the plugin download fails, the hooks are still installed and the command exits with an error and a retry command.

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

uninstall

Remove what Omnodex installed.

omnodex uninstall [target] [project]

Removes the project’s Omnodex hooks. When the agent records every project, it also leaves this project out, so it is no longer recorded; omnodex install there records it again. With no target, applies to every agent.

Flag	Description
--everywhere	Stop recording every project: remove the hooks from the agent’s user settings
--plugin	Remove the agent’s Omnodex plugin
--confirm	Do not ask before removing
--unattended	Remove without a terminal, for scripts and fleet tools. The removal is recorded and raises a MEDIUM finding

Removing monitoring needs a person at an interactive terminal, so an agent’s shell cannot switch Omnodex off. Without a terminal, uninstall refuses and changes nothing. A script or fleet tool passes --unattended instead, which skips the prompt:

omnodex uninstall codex ~/projects/app --unattended

Every install, removal, update and left-out project is recorded on this machine, so a removal you made can be told apart from one you didn’t.

Only Omnodex’s own entries are removed. Event data is not affected.

status

Show what records a project: every-project hooks, the project’s own hooks, plugins, and whether the project is left out.

omnodex status [project] [--all]

Flag	Description
--all	List everything installed on this host, including left-out projects, 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: for example, the stream’s owner paused receiving, or this machine’s stream secret is not the stream’s.

It also shows whether recording and uploads are on or paused on this machine, how long a timed pause has left, and the enforcement mode.

The monitoring: line checks that what Omnodex installed is still in place for each agent: its hook entry, hooks not switched off, its plugin and MCP entry. Each problem names the file and the command that restores monitoring. A change no Omnodex command made is also recorded as a monitoring tampering finding.

connect

Connect this host to your hosted dashboard account.

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

Flag	Description
--token	Use this connection token instead of running the device code flow. It is checked and saved to stream-config.json.
--secret	Use this stream secret. It is checked against the stream’s and saved. --passphrase still works.
--platform	Platform identifier sent with the connection, for example codex
--api	API endpoint, for self-hosted instances

Without a connection 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 working token already stored, it prints a one-time connection link to open while signed in.

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

connect also gets a machine uploading again:

• Token revoked: it starts the sign-in, and the device page offers to re-authorize the same stream, keeping its history. See Authorizing a machine again.
• Token rotated in the dashboard: it picks up the new token by proving it holds the stream secret. After a rotate made On the machine, pass the new token with --token.
• A token but no secret, for a stream that already has one: it asks for the stream’s secret (--secret) instead of generating a new one.

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_...>] [--secret <stream secret>]

Credentials come from flags, then OMNODEX_API_TOKEN and OMNODEX_STREAM_SECRET, then stream-config.json. Requires the Hosted tier or above. Each host uploads under its own random machine ID; set machine.label in config.json for a readable name, which is encrypted before it leaves the machine.

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.

If the stream’s owner rotated the token, sync picks up the new one first and saves it. If this machine’s stream secret is not the stream’s, it stops without uploading and says how to fix it.

record and sync pause

Pause recording, or uploads, on this machine. See Pausing Recording and Uploads.

omnodex record pause [duration] | resume | status
omnodex sync pause [duration] | resume | status

Command	Effect
record pause	Nothing is captured or uploaded on this machine
sync pause	Events are still captured and shown in the local dashboard, but never uploaded, even after you resume
resume	Turns the switch back on
status	Shows the switch and any time left

Durations look like 30m, 1h, 2d or 1h30m, up to 30 days; without one, the pause lasts until resumed. Pausing needs an interactive terminal and a typed confirmation, so an agent cannot run it. Each pause writes start and end markers that both dashboards show.

enforce

Choose whether Omnodex acts on tool calls. See Shadow Mode and Guardrails.

omnodex enforce monitor | shadow | guardrails | status

Mode	Effect
monitor	Record and flag; never act (the default)
shadow	Also note on each finding whether Omnodex would have stopped the call; never act
guardrails	Stop, or hold for confirmation, the calls your settings say to (Pro)
status	Show the current mode

The mode is saved in omnodex-config.json and applies from the next tool call. Switching to guardrails needs a Pro or Enterprise plan and fetches the guardrails module; status then names the module’s version, or why it is not in use. Switching to or from guardrails also updates the Claude Code and Antigravity hooks Omnodex installed. Leaving guardrails needs an interactive terminal and a typed confirmation, so an agent cannot run it.

policy

Decide what happens to findings like one you have seen. See Choosing what stops.

omnodex policy list
omnodex policy add <match> [target] [--project <folder> | --here] <effect> [--note <text>]
omnodex policy remove <id>
omnodex policy pull

Part	Options
Match (one)	--rule <id>, --category <name>, --severity <LOW | MEDIUM | HIGH | CRITICAL>
Target (at most one)	--path, --reads, --writes, --destination, --command-prefix, --tool (with optional --server), --credential
Effect (at least one)	--block or --hold (Pro), --allow, --mute or --unmute, --set-severity <level>

list shows every entry with its id, settings written in the older form included, and remove takes that id. Entries are saved in omnodex-config.json and apply from the next tool call. Allowing, muting, lowering a severity, or removing an entry that blocks, holds, unmutes or raises a severity needs an interactive terminal and a typed confirmation, so an agent cannot run it.

pull fetches the policy your account holds for this machine now, instead of waiting for the next background sync. It needs a machine connected to a dashboard account (omnodex connect) on a paid plan, and says when the copy is already current, when the account has no policy yet, or when pulling is switched off with OMNODEX_POLICY_PULL=0. If a pull fails, the copy you already have stays in use. list shows the account’s entries after your own, read only: change them in the hosted dashboard.

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. It answers only a browser on the same machine; see Who can reach it. 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 Local Dashboard and Hosted 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

Flag	Description
--all	Delete everything in the Omnodex home instead of one session. Needs --confirm
--confirm	Confirm --all
--unattended	Clear without a terminal, for scripts. The clear is recorded and raises a MEDIUM finding

Clearing erases the record of what your agents did, so it needs a person at an interactive terminal, the same as uninstall. An agent’s shell can’t do it: without a terminal, clear refuses and deletes nothing. A script passes --unattended instead:

omnodex clear --all --confirm --unattended

Every clear is recorded as a monitoring change. After clear --all --confirm, that record is the first entry in a new, otherwise empty event log, and on a connected machine Omnodex tries to send it to the hosted dashboard before the connection is deleted. A scripted clear also raises a MEDIUM self-protection finding (RULE_SELF_PROTECTION_UNATTENDED_REMOVAL), so it stays visible even when it was planned.

Danger

clear --all --confirm deletes the whole Omnodex home directory, not only events: configuration files, the hosted dashboard connection in stream-config.json, and the hook launchers in it are removed too. It cannot be undone.

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] [--refresh-plugins]

Flag	Description
--check	Show available updates, and plugins that would change, without installing
--refresh-launchers	Rewrite the hook launchers in ~/.omnodex/bin/ without updating
--refresh-plugins	Bring installed plugins to the versions this release ships, 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 install -g omnodex@<latest version>. Either way it then brings each installed plugin to the version the new release ships, keeping a version chosen with --plugin-version until a newer one ships. 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_STREAM_SECRET	(none)	Stream secret. Overrides stream-config.json. OMNODEX_SYNC_PASSPHRASE still works.
OMNODEX_AUTO_SYNC	(unset)	Set to 0 to turn automatic sync off on this host
OMNODEX_POLICY_PULL	(unset)	Set to 0 to stop pulling the account’s finding policy 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
OMNODEX_DOWNLOADS_URL	https://downloads.omnodex.com	Where install and update download plugins from, for a mirror

Next steps

• Configuration - Configuration files
• Quick Start - Get started