Orq CLI

Use the official command-line interface to interact with the Orq.ai API from a terminal, CI, or scripts. Works against Orq.ai SaaS out of the box and against self-hosted deployments with a single flag.

GitHub

orq-cli

Installation

npm install -g @orq-ai/cli

curl -fsSL https://raw.githubusercontent.com/orq-ai/orq-cli/main/install.sh | sh

The npm package requires Node.js 14 or newer and downloads the matching native binary automatically. The curl script installs a raw binary to ~/.orq/bin/orq. Pre-built release binaries for each platform are available on the Releases page.

Authentication

The CLI supports two auth methods. Both respect --profile <name> to keep multiple identities (personal account, CI, self-hosted customer) side by side.

OAuth device login
API key

orq auth login

Walks through a browser-based device-authorization flow, writes credentials to ~/.orq/sessions/default.json, and picks an active workspace. Re-run orq auth login to refresh the session. Sign out with orq auth logout.

export ORQ_API_KEY=sk_live_...
orq agents list

Get an API key from Organization > API Keys. For multiple keys, save each one to a profile:

orq auth add-profile apikey ci <api-key>
orq --profile ci agents list

ORQ_API_KEY takes priority over an active OAuth session. If it is set in the terminal environment, every command uses that key instead of the credentials from orq auth login, which can apply the key’s own project restrictions instead of the expected workspace access. Unset it to fall back to the OAuth session:

unset ORQ_API_KEY

Profiles

Every command accepts --profile <name> (or the ORQ_PROFILE env var). Each profile has its own session file at ~/.orq/sessions/<name>.json and its own API key credentials in ~/.orq/credentials.json. The default profile is default.

# personal account against SaaS
orq auth login

# work account against SaaS
orq --profile work auth login
orq --profile work workspace use marketing

# self-hosted customer
orq --profile acme auth login --api-base-url https://orq.acme.internal

--api-base-url sets the host to authenticate against for a self-hosted profile at login time; it is stored in the session. After login, every command on that profile automatically routes to the stored host. Override the host for a single call with --server <url> or ORQ_SERVER=<url> without changing the stored session.

Quick start

With the CLI installed and authenticated, run a resource command to confirm everything works:

orq whoami                # verify identity
orq agents list           # example resource command

Diagnostics

orq doctor
orq doctor --json          # machine-readable

doctor reports the CLI binary and runtime, active profile and session file path, resolved base URLs and their source (flag, session, env, default, derived), auth status, and reachability probes against each endpoint.

Output formats

TOON (Token-Oriented Object Notation) is the default renderer: a compact, human-readable table format. Switch it per call or persist a new default.

orq agents list                             # TOON (default, human-readable)
orq agents list --output-format json        # JSON
orq agents list --output-format yaml        # YAML
orq agents list --json                      # shortcut for JSON
orq agents list -q 'data[].display_name'    # JMESPath query

Persist a new default with orq default-format <json|yaml|toon>.

Workspaces

orq workspace list         # list workspaces available to the active identity
orq workspace use <key>    # switch active workspace (persists in the session)
orq whoami                 # current user + active workspace + URL config

Command reference

Built-in commands

Command	Purpose
`orq auth login`	OAuth device login
`orq auth logout`	Revoke refresh token, clear local session
`orq auth whoami`	Show current identity (alias: `orq whoami`)
`orq auth add-profile apikey <name> <key>`	Save an API key profile
`orq auth list-profiles`	List configured credential profiles
`orq workspace list`	List workspaces
`orq workspace use <key>`	Switch active workspace
`orq doctor`	Diagnose config, auth, reachability
`orq request <method> <path>`	Raw API escape hatch (uses configured auth)
`orq server list`	List OpenAPI-registered servers
`orq completion bash\|zsh\|fish\|powershell`	Generate shell completions
`orq default-format <json\|yaml\|toon>`	Persist a default output format

Resource commands

Use --help on any group for the full surface (inputs, body fields, examples):

Command	Subcommands
`orq agents`	`create`, `delete`, `get-response`, `invoke`, `list`, `refresh-agent-card`, `retrieve`, `run`, `stream`, `stream-run`, `update`
`orq agents-responses`	`create`
`orq api-keys`	`create`, `delete`, `get`, `list`, `list-capabilities`, `update`
`orq budgets`	`check`, `create`, `delete`, `get`, `get-consumption`, `list`, `reset-consumption`, `update`
`orq chat`	`create`
`orq chunking`	`parse`
`orq completions`	`create`
`orq datasets`	`clear`, `create`, `create-datapoint`, `delete`, `delete-datapoint`, `list`, `list-datapoints`, `retrieve`, `retrieve-datapoint`, `update`, `update-datapoint`
`orq deployments`	`get-config`, `invoke`, `list`, `stream`
`orq embeddings`	`create`
`orq evals`	`all` (list evaluators), `create`, `delete`, `invoke`, `list-versions`, `update`
`orq feedback`	`create`, `delete`, `evaluation`, `evaluation-remove`
`orq files`	`content` (download), `delete`, `get`, `list`, `update`, `upload`
`orq identities`	`create`, `delete`, `list`, `retrieve`, `update`
`orq images`	`edit`, `generate` (create), `variation`
`orq knowledge-bases`	`create`, `create-chunks`, `create-datasource`, `delete`, `delete-chunk`, `delete-chunks`, `delete-datasource`, `list`, `list-chunks`, `list-chunks-paginated`, `list-datasources`, `retrieve`, `retrieve-chunk`, `retrieve-datasource`, `search`, `update`, `update-chunk`, `update-datasource`
`orq management-keys`	`create`, `delete`, `get`, `list`, `list-capabilities`, `update`
`orq memory-stores`	`create`, `create-document`, `create-memory`, `delete`, `delete-document`, `delete-memory`, `list`, `list-documents`, `list-memories`, `retrieve`, `retrieve-document`, `retrieve-memory`, `update`, `update-document`, `update-memory`
`orq models`	`azure-foundry-deployments`, `create`, `create-autorouter`, `create-aws-bedrock`, `create-openai-like`, `create-vertex`, `delete`, `disable`, `enable`, `import-litellm`, `list`, `list-litellm`, `update`, `update-autorouter`, `update-aws-bedrock`, `update-openai-like`, `validate`, `validate-aws-bedrock`
`orq moderations`	`create`
`orq notifiers`	`create`, `delete`, `get`, `list`, `update`
`orq ocr`	`ocr` (extract text)
`orq pii`	`detect`, `redact`, `restore`
`orq projects`	`create`, `delete`, `get`, `list`, `update`
`orq prompts`	`create`, `delete`, `get-version`, `list`, `list-versions`, `retrieve`, `update`
`orq reporting`	`query`
`orq rerank`	`create`
`orq responses`	`create`, `get`
`orq schedules`	`create`, `delete`, `list`, `retrieve`, `trigger`, `update`
`orq skills`	`create`, `delete`, `get`, `list`, `update`
`orq speech`	`create`
`orq telemetry`	`query`
`orq tools`	`create`, `delete`, `get-version`, `list`, `list-versions`, `retrieve`, `update`
`orq traces`	`aggregate`, `create` (annotate a span), `delete` (remove an annotation), `get`, `get-span`, `list-facet-values`, `list-facets`, `list-fields`, `list-spans`, `query-oql`, `search`
`orq transcriptions`	`create`
`orq translations`	`create`
`orq webhooks`	`count`, `create`, `delete`, `generate-secret`, `get`, `list`, `query`, `update`

Orq SDK

Platform APIs

Gateway APIs

Enterprise APIs (coming soon)

Orq CLI

GitHub

orq-cli

Installation

Authentication

Profiles

Quick start

Diagnostics

Output formats

Workspaces

Command reference

Built-in commands

Resource commands

​GitHub

orq-cli

​Installation

​Authentication

​Profiles

​Quick start

​Diagnostics

​Output formats

​Workspaces

​Command reference

​Built-in commands

​Resource commands

GitHub

Installation

Authentication

Profiles

Quick start

Diagnostics

Output formats

Workspaces

Command reference

Built-in commands

Resource commands