omnara

omnara [options] [command]omnara login [--no-browser] [--token-name name]omnara config [--org org-id] [--project project-id] [--api-url url] [--issuer-url url]omnara agents subcommand [options]

omnara is the command-line client for Omnara, an open-source managed agent platform (Apache 2.0). It launches and manages durable AI agents, machines, model providers, secrets, skills, integrations, and related resources through the same REST API as the dashboard and TypeScript SDK. The npm package is omnara; the binary name is omnara. Node.js 22 or later is required. Run it with npx omnara or install the package globally.The CLI is a Commander program generated from the Omnara SDK and OpenAPI operations, plus a few custom commands (`login`, `logout`, `config`, `agents chat`, `agents events stream`, `machines create-local`). Most list and get commands print a table or record; pass --json for the raw JSON response. Field flags can be replaced with --body JSON; flags override that body.Hosted API requests go to `https://api.omnara.com/v1` and browser login uses `https://app.omnara.com`. Self-hosted deployments serve the same API under `/api/v1` on their own origin. A first command that needs an account starts device login in the browser when stdin is a terminal; otherwise set OMNARA_API_KEY or run omnara login.

-h, --help

Print usage. Every command accepts -h / --help.

Organization ID. Defaults from the config file or OMNARA_ORG_ID.

Project ID. Defaults from the config file or OMNARA_PROJECT_ID.

Print the raw JSON response instead of a table or record.

Full request body as JSON; field flags override it.

Path to an agent config (`.yaml`, `.yml`, or `.json`). Used by agents launch and profiles create.

Inline YAML or JSON agent config.

Existing agent config ID (acfg prefix).

Agent profile ID (aprf prefix). Runs that profile's current config unless a config is also given.

First user message on launch, or a single text block on agents input.

Display name for a launched agent, profile, or similar resource.

With login, print the approval URL instead of opening a browser.

~/.config/omnara/config.json

Saved token, default organization, default project, and API URLs. The directory is created mode `0700` and the file is written mode `0600`. A legacy base-url key is dropped on load.

$ {
  "token": "",
  "org_id": "",
  "project_id": "",
  "api_url": "",
  "issuer_url": ""
}

$ version: v1
instruction: |
  You are an engineering assistant. Use your machine to run commands.
model:
  provider_config: omnara-openrouter
  name: anthropic/claude-fable-5.1
machine_sources:
  - machine_pool_name: default-pool

login

Open a browser (or print the approval URL with --no-browser) and save an API token. --token-name labels the created token.

Remove the saved token from the config file. The token stays valid until revoked under Personal tokens in the account menu.

Show or save defaults. --org, --project, --api-url, and --issuer-url write those keys. Changing --org clears the saved project. config select interactively chooses an organization and project (needs a terminal).

Print the authenticated user and their organizations.

Launch and manage agents. Subcommands: list, get agent-id, launch, update agent-id, cancel agent-id, archive agent-id, mcp-add agent-id, chat [agent-id], input agent-id, events, interactions. launch takes --file, --source, --config, and/or --profile, plus --name and --message. chat needs an interactive terminal. input sends --message or --content-blocks; --delivery-mode is `queued` or `steering`. events list / events stream read the timeline; stream accepts --after-sequence and --deltas. cancel stops the current turn; archive retires the agent (no unarchive). Agent activity state is running, waiting on interaction, idle, or archived.

Manage BYO machines. create-local creates a machine, mints a daemon token, and installs omnarad on this computer (--display-name required). It refuses if `~/.omnarad` (or OMNARA_HOME) already holds a daemon; run omnarad uninstall first. create prints a one-time token and install command for another computer. Also list, get, update, delete.

Agent launch templates. create requires --name and a config via --file, --source, or --config. Also list, get, update, rename, delete, mcp-add.

Share resources with a project: skills, secrets, machines, pools, models. grant machines add requires --machine-id.

Organization and project administration, invitations, org API keys, and personal access tokens.

Machine pools, model provider configs and models, secrets (including mcp-oauth), skill packages, memory stores, cron triggers, and project integrations (Slack, GitHub, Discord).

OMNARA_API_KEY

Bearer token. Overrides the token in the config file. Curl and the SDK use a similarly named token variable; the CLI reads this one.

Default organization ID. Overrides the organization key in the config file.

Default project ID. Overrides the project key in the config file.

API root used for requests. Default `https://api.omnara.com/v1`. Self-hosted example: `http://localhost:8000/api/v1`.

Web app origin used for login and browser links. Default `https://app.omnara.com`.

Requires Node.js 22 or later. agents chat and config select need an interactive terminal. Without a saved token and without a TTY, commands fail with: not logged in; run omnara login or set OMNARA_API_KEY. logout does not revoke the token on the server.machines create-local will not overwrite an existing daemon home. Public resource IDs use a type prefix (agt, acfg, aprf, mch, org, proj, and others) plus 26 lowercase base32 characters; treat them as opaque.Archiving an agent deletes its integration subscriptions, stops work, drops queued inputs, and releases pooled machines. Machines you connected yourself, configs, and profiles remain.

Omnara is an Apache-2.0 project at omnara-ai/omnara. The CLI lives in `frontend/packages/cli` and is published to npm as omnara. The same repository ships the control plane, dashboard, TypeScript SDK (`@omnara/sdk`), and the omnarad machine daemon.

omnarad(1), npx(1), npm(1), node(1), docker(1), docker-compose(1), curl(1), jq(1)

Source code · Homepage · Documentation