Omnigent CLI Reference: All Commands and Flags

The omnigent and omni commands are identical entry points to the Omnigent CLI. Every subcommand is documented here. The CLI manages agent sessions, the local server daemon, remote server connections, cloud sandboxes, and credential configuration — all from one tool.

omni is an alias for omnigent. Both commands accept exactly the same subcommands and flags.

omnigent (root)

Bare omnigent with no arguments on an interactive TTY behaves like omnigent run — it resolves the configured default agent or first-run plan, and drops into omnigent setup when nothing is configured yet. In a non-interactive context (pipe, CI, no TTY) it falls back to --help. Global flag:

Flag	Description
`--version`	Print the installed Omnigent version and exit.

Path shortcuts:

omnigent myagent.yaml is equivalent to omnigent run myagent.yaml
omnigent --harness claude-sdk is equivalent to omnigent run --harness claude-sdk

omnigent run

Start a session with an Omnigent agent.

omnigent run [AGENT] [OPTIONS]

AGENT may be an agent YAML file or an agent directory. Without AGENT, pass --server to connect to a server directly, or --harness to launch a built-in harness.

Flags

Flag	Default	Description
`--harness TEXT`	—	Harness to use: `claude-sdk` (alias `claude`), `openai-agents`, `codex`, `open-responses`, or `pi`. Without an AGENT, launches that harness directly.
`--model TEXT`	—	Model to use for the agent.
`-p, --prompt TEXT`	—	Send this as the first message when the REPL starts (headless one-shot mode).
`--system-prompt TEXT`	—	Override the agent’s instructions for this run.
`-r, --resume [CONV_ID]`	—	Resume a prior conversation. Without a value, opens an interactive picker. With a conversation id, attaches directly.
`-c, --continue`	`false`	Continue the most recent conversation for this agent.
`--fork SESSION_ID`	—	Fork an existing session by id and open the REPL on the fork. Mutually exclusive with `--resume` and `--continue`.
`--server URL`	—	Remote Omnigent URL. Uploads the local YAML as an ephemeral agent, spawns a local runner that tunnels to this server, and connects the REPL. Pass `--server ""` to auto-spawn a persistent local server.
`--no-session`	`false`	Use a fresh temporary local session store for this run.
`--log / --no-log`	`false`	Write a JSON dump of the conversation to `~/.omnigent/logs/` on exit.
`--debug-events`	`false`	Enable the SSE-to-UI debug pipeline: event tape overlay, JSONL event log, and pipeline stage counters.
`--tools TEXT`	—	Client-side tool set name (e.g. `coding`) for shell access.

Examples:

# Launch Claude directly
omnigent run --harness claude-sdk

# Run an agent YAML file
omnigent run examples/hello_world.yaml

# Override harness and model
omnigent run examples/hello_world.yaml --harness codex --model gpt-4o-mini

# Headless one-shot
omnigent run --harness codex -p "review the last commit"

# Connect a local agent to a remote server
omnigent run examples/agent.yaml --server https://myapp.databricksapps.com

# Resume latest conversation
omnigent run examples/agent.yaml --continue

omnigent claude

Launch Claude Code in an Omnigent terminal.

omnigent claude [OPTIONS] [CLAUDE_ARGS...]

Ensures the host daemon, asks the daemon-spawned runner to launch Claude Code in a tmux terminal, and attaches the current TTY to it. Extra positional arguments after -- are passed through to the claude CLI unchanged.

Flags

Flag	Default	Description
`--server URL`	—	Remote Omnigent URL. Omit or leave empty to auto-spawn a local server.
`-r, --resume [CONV_ID]`	—	Resume a prior Omnigent conversation. No value opens an interactive picker scoped to claude-native sessions.
`--use-native-config`	`false`	Use your existing `~/.claude/` configuration instead of the configured Omnigent provider.
`--profile-startup`	`false`	Print native Claude startup timing marks to stderr. Also enabled by `OMNIGENT_CLAUDE_STARTUP_PROFILE=1`.

Examples:

omnigent claude
omnigent claude --resume conv_abc123
omnigent claude --resume                             # interactive picker
omnigent claude --server https://myapp.databricksapps.com

omnigent codex

Launch Codex TUI in an Omnigent terminal.

omnigent codex [OPTIONS] [CODEX_ARGS...]

Ensures the host daemon, asks the runner to launch the Codex TUI in a tmux terminal, and attaches this TTY.

Flags

Flag	Default	Description
`--server URL`	—	Remote Omnigent URL. Omit or leave empty to auto-spawn a local server.
`-r, --resume [CONV_ID]`	—	Resume a prior Omnigent conversation. No value opens an interactive picker.
`--model TEXT`	—	Codex model to use for the native thread.
`-p, --prompt TEXT`	—	Send this as the first message after the Codex TUI starts.

Examples:

omnigent codex
omnigent codex --resume conv_abc123
omnigent codex --resume                             # interactive picker
omnigent codex --server https://myapp.databricksapps.com

omnigent attach

Attach the REPL to a live session — never starts anything.

omnigent attach [CONVERSATION_ID] [OPTIONS]

attach is a thin client: it joins an already-running conversation and streams its I/O. It never spawns a server, runner, or harness, and errors loudly when there is no live session to attach to. To start a session use omnigent run; to reopen a stored one use omnigent resume.

Flags

Flag	Default	Description
`--server URL`	—	Omnigent server hosting the session. Defaults to the configured server or a local server already running in the background.
`--tools TEXT`	—	Client-side tool set name for shell access.
`--debug-events`	`false`	Enable the SSE-to-UI debug pipeline.

Examples:

omnigent attach conv_abc123
omnigent attach conv_abc123 --server https://myapp.databricksapps.com

omnigent resume

Resume an Omnigent conversation, auto-dispatching by runtime.

omnigent resume [CONV_ID] [OPTIONS]

With CONV_ID: looks up the conversation and dispatches to the matching wrapper — claude-native sessions land in omnigent claude, everything else surfaces a hint to use omnigent run --resume <id> <agent.yaml>. Without CONV_ID: opens a cross-agent picker (requires --server).

Flag	Default	Description
`--server URL`	—	Remote Omnigent server URL. Required for the picker (no id) mode.

omnigent resume conv_abc123
omnigent resume --server https://myapp.databricksapps.com

omnigent server

Manage the Omnigent server daemon.

omnigent server (foreground)

omnigent server [OPTIONS]

Bare omnigent server runs the server in the foreground (Ctrl-C to stop) — suitable for deploys and Docker.

Flags

Flag	Default	Description
`--host TEXT`	`127.0.0.1`	Interface to bind to.
`-p, --port INT`	`6767`	Port to listen on.
`--database-uri TEXT`	`sqlite:///<data-dir>/chat.db`	Database URI.
`--artifact-location TEXT`	`<data-dir>/artifacts`	Path for artifact storage.
`-c, --config PATH`	—	Path to a YAML server config file.
`--execution-timeout INT`	`7200`	Max wall-clock seconds per agent execution.
`--agent PATH`	—	Pre-register an agent from a directory at startup. Repeatable.
`--open / --no-open`	`--open`	On first boot of accounts auth, open the magic-redeem URL in the browser. Pass `--no-open` for headless / SSH / Docker.
`--admin-password TEXT`	—	Set the first-run admin password non-interactively.

omnigent server start

Ensure the managed background server is running.

omnigent server start

Reuses a healthy background server if one is already up (started here or by a prior run/host). Otherwise spawns a detached one on a free loopback port and prints its URL.

omnigent server stop

Stop the background server and local host daemon.

omnigent server stop [--force]

Flag	Description
`--force`	SIGKILL the local host daemon if it does not exit on SIGTERM.

omnigent server status

Show whether the background server is running.

omnigent server status [--json]

Reports the pid, port, URL, live-session count, and whether a local host daemon is attached.

omnigent host

omnigent host [URL] [OPTIONS]

Runs as a foreground daemon — Ctrl-C to stop. When no --server URL is given, starts (or reuses) a local Omnigent server. The server URL may be given positionally (omnigent host https://example.com) or via --server.

Flag	Description
`--server URL`	Remote Omnigent server URL.

Examples:

omnigent host https://omnigent-app.databricksapps.com
omnigent host ""     # spawn + connect to a local server

omnigent host status

Inspect host daemon, runner, and session status.

omnigent host status [--server URL] [--all] [--json]

omnigent host stop

Stop host daemon sessions, then stop daemon processes.

omnigent host stop [--server URL] [--all] [--daemon-only] [--force]

omnigent host stop-session

Stop specific sessions without stopping a daemon.

omnigent host stop-session SESSION_ID... [--server URL] [--force]

omnigent stop

Stop everything Omnigent is running on this machine.

omnigent stop [--force]

The off switch: stops every host daemon (local and remote-targeted) and the detached background server. To stop only hosting while keeping the local server up, use omnigent host stop instead.

Flag	Description
`--force`	Continue past failures and SIGKILL daemons that do not exit on SIGTERM.

Authenticate with a remote Omnigent server.

omnigent login SERVER_URL

Probes the server’s auth mode and runs the matching flow automatically:

accounts mode: prompts for username + password, stores the JWT in ~/.omnigent/auth_tokens.json.
OIDC mode: opens the browser, polls the CLI ticket endpoint, stores the JWT.
header mode: prints a hint that no login is needed.
Databricks-fronted (a Databricks App or workspace-hosted Omnigent): runs databricks auth login against the right workspace automatically.

omnigent login https://myserver.databricksapps.com
omnigent run --server https://myserver.databricksapps.com   # uses stored token

omnigent setup

Launch the interactive credential setup flow.

omnigent setup [--internal-beta | --no-internal-beta]

By default, runs the standard model/credential picker — choose a provider for each harness (Claude, Codex, Pi) and set your defaults. Pass --internal-beta to configure Databricks internal-beta defaults and authentication instead. After setup, list configured credentials with omnigent config list.

omnigent config

Get, set, and view Omnigent defaults and credentials.

omnigent config list

omnigent config list

Print the effective defaults (user + project-level) and configured model credentials grouped by harness, with each harness’s default marked.

omnigent config set

omnigent config set [--global] KEY=VALUE...

Set one or more defaults. Without --global, writes to .omnigent/config.yaml in the current directory (project-level, like .git/config). With --global, writes to ~/.omnigent/config.yaml. Supported keys: auto_open_conversation, default_agent, harness, model, server.

omnigent config set default_agent=examples/hello_world.yaml
omnigent config set --global server=https://myapp.databricksapps.com
omnigent config set --global model=databricks-claude-sonnet-4-6

omnigent config unset

omnigent config unset [--global] KEY...

Remove one or more defaults from the config.

omnigent config unset server
omnigent config unset --global default_agent

omnigent sandbox

Run an Omnigent host inside a remote cloud sandbox. Available when at least one sandbox provider extra is installed (pip install 'omnigent[modal]' or pip install 'omnigent[daytona]').

omnigent sandbox SUBCOMMAND [OPTIONS]

omnigent sandbox create

Provision a new cloud sandbox and bootstrap Omnigent into it.

omnigent sandbox create --provider PROVIDER [OPTIONS]

omnigent sandbox connect

omnigent sandbox connect --provider PROVIDER --sandbox-id ID --server URL

For provider-side sandbox lifecycle management (list, status, delete, start, stop), use the provider’s own CLI directly — for example modal sandbox list.

omnigent debug

Internal maintenance commands (advanced — not needed for normal use).

omnigent debug db-upgrade

Upgrade the schema of an Omnigent tracking database to the latest version.

omnigent debug db-upgrade URL

URL is a SQLAlchemy database URL, e.g. sqlite:////absolute/path/to/chat.db or postgresql://user:pass@host/dbname.

Schema migrations can be slow and are not guaranteed to be transactional. Always back up your database before running migrations.

omnigent debug migrate-accounts-to-oidc

Remap user identities when switching the accounts provider to OIDC.

omnigent debug migrate-accounts-to-oidc URL [--map OLD=NEW] [--domain DOMAIN] [--commit] [--force]

# Dry run: append the org domain to every username
omnigent debug migrate-accounts-to-oidc sqlite:///chat.db --domain example.com

# Apply it
omnigent debug migrate-accounts-to-oidc sqlite:///chat.db --domain example.com --commit

Get Started

Core Concepts

Guides

Deployment

Reference

Omnigent CLI Reference: All Commands and Flags

omnigent (root)

omnigent run

omnigent claude

omnigent codex

omnigent attach

omnigent resume

omnigent server

omnigent server (foreground)

omnigent server start

omnigent server stop

omnigent server status

omnigent host

omnigent host status

omnigent host stop

omnigent host stop-session

omnigent stop

omnigent setup

omnigent config

omnigent config list

omnigent config set

omnigent config unset

omnigent sandbox

omnigent sandbox create

omnigent sandbox connect

omnigent debug

omnigent debug db-upgrade

omnigent debug migrate-accounts-to-oidc

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Deployment

Reference

Documentation Index

​omnigent (root)

​omnigent run

​omnigent claude

​omnigent codex

​omnigent attach

​omnigent resume

​omnigent server

​omnigent server (foreground)

​omnigent server start

​omnigent server stop

​omnigent server status

​omnigent host

​omnigent host status

​omnigent host stop

​omnigent host stop-session

​omnigent stop

​omnigent login

​omnigent setup

​omnigent config

​omnigent config list

​omnigent config set

​omnigent config unset

​omnigent sandbox

​omnigent sandbox create

​omnigent sandbox connect

​omnigent debug

​omnigent debug db-upgrade

​omnigent debug migrate-accounts-to-oidc

Build docs developers (and LLMs) love

omnigent (root)

omnigent run

omnigent claude

omnigent codex

omnigent attach

omnigent resume

omnigent server

omnigent server (foreground)

omnigent server start

omnigent server stop

omnigent server status

omnigent host

omnigent host status

omnigent host stop

omnigent host stop-session

omnigent stop

omnigent login

omnigent setup

omnigent config

omnigent config list

omnigent config set

omnigent config unset

omnigent sandbox

omnigent sandbox create

omnigent sandbox connect

omnigent debug

omnigent debug db-upgrade

omnigent debug migrate-accounts-to-oidc