Orq CLI

This feature is in Beta.

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://cli.orq.ai/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, verifies it against the release’s published checksum, and runs orq setup; pass --no-setup to the script to skip that step, --version <tag> to pin a release, or --install-dir <dir> to choose the location. After an npm install, run orq setup. Pre-built release binaries for each platform are available on the Releases page. An Orq.ai account is required. Sign up at my.orq.ai. Bug reports and feature requests go to GitHub issues.

Quick start

orq setup                # sign in, create a project-scoped API key, wire coding agents
orq status               # verify identity, workspace, project, and credential
orq workspace list       # see available workspaces
orq agents list          # example resource command
orq doctor               # diagnose auth, config, and endpoint reachability

Coding agents

orq setup signs in through the browser, creates a project-scoped API key, and wires the coding agents already on the machine to route their model calls through the AI Gateway. It writes the key to ~/.orq/env and offers to source that file from the shell profile, so later commands pick up ORQ_API_KEY. It can also add the Orq MCP server and Orq Skills. Supported agents: Claude Code, Codex, OpenCode, Kimi Code, Kilo, Pi, GitHub Copilot CLI, and Gemini CLI. orq connect wires agents permanently, per agent and per capability (gateway, tracing, skills, mcp). It edits each agent’s own config and registers Orq.ai as an available model provider, never as the agent’s default. orq disconnect removes exactly what connect wrote. Claude Code has no provider config, so connect gives it skills and mcp only; Copilot and Gemini are launch-only. For those three, orq launch is how model calls route through the AI Gateway.

orq connect                 # every detected agent, every capability it can take
orq connect claude skills   # one agent, one capability
orq connect --local         # write into this project instead of machine-wide
orq connect --dry-run       # show the files that would change, write nothing
orq connect --status        # what's wired on this machine
orq connect -y              # answer yes to every confirmation
orq disconnect              # take it all back out

connect writes machine-wide by default (--global). --local writes mcp and skills into the current project instead, for the agents that read a project config: Claude Code, Codex, Kimi Code, OpenCode, and Kilo. gateway and tracing are machine-wide whatever the flag says. --api-key <key> uses a specific key for that run instead of the saved credential. orq setup takes the same --global / --local choice, plus --capability gateway|skills|mcp (repeatable) to wire a subset and --no-project to leave the session unscoped. orq launch <agent> starts a coding agent routed through the AI Gateway for that session only. Nothing is left on disk after the session ends. Every call is traced with cost, tokens, and latency, and Budgets and rate limits apply.

orq launch claude           # also: codex, opencode, kimi, kilo, pi, copilot, gemini
orq launch codex --model anthropic/claude-sonnet-5 --no-mcp
orq launch codex --dry-run  # print the resolved command and env, key redacted

Launch flags: --model, --models (extra model ids for OpenCode, Kilo, Kimi Code, and Pi), --base-url, --mcp (the default) and --no-mcp, --no-skills, --dry-run, and --no-fetch-models on every agent except Claude Code. One-shot prompts use -p/--prompt, which orq maps to each agent’s own syntax; Claude Code is the exception, where -p is Claude’s own flag forwarded untouched and --prompt is not accepted. Global flags such as --profile go before the agent name. Everything after -- goes to the agent untouched. The same command works headless. Pass a prompt and the agent runs once and exits. In CI, put an API key in the environment instead of a browser login. Launch reads ORQ_API_KEY first, then the login session.

export ORQ_API_KEY=sk_live_...
orq launch claude -p "summarize yesterday's failed traces"

Without ORQ_API_KEY, launch mints a fresh workspace token from the login session at start, and that token expires an hour later. It is handed to the agent as an environment variable, so it cannot be refreshed mid-session: an agent session that runs past the hour starts failing. The long-lived key orq setup mints is used by orq connect for permanent wiring, not by launch. For long or unattended sessions, export an API key.

The Orq Skills ship inside the CLI binary and update with it. orq launch links them for the session and orq connect skills installs them permanently. orq skills is a different command: it manages Skills entities on the platform.

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 profile add ci --api-key-file ci.key   # `-` reads the key from stdin
orq --profile ci agents list
orq auth profile use ci                         # persist the pick

The key is read from a file rather than passed as an argument, so it stays out of shell history. Omit --api-key-file at a terminal and the CLI prompts for it without echo.

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. The CLI prints Using ORQ_API_KEY from environment on stderr when this happens. Unset it to fall back to the OAuth session:

unset ORQ_API_KEY

.env files in the working directory are not read. Set ORQ_DOTENV=1 to load ORQ_-prefixed variables from one for a single command; orq doctor then reports the file as the auth source. orq auth sessions lists saved browser logins by host, with their workspace, project, user, and status.

Profiles

A profile is one complete identity: its own credential, its own session file at ~/.orq/sessions/<name>.json, and its own API key entry in ~/.orq/credentials.json. The default profile is default. Every command accepts --profile <name> (or the ORQ_PROFILE env var). The profile’s credential already carries its workspace and project, so --profile is all a command needs. Do not combine it with --workspace or --project; those flags are for pointing a single call at a different target than the active session, not for scoping a profile.

# personal account against SaaS
orq auth login

# work account, its own credential and workspace
orq --profile work auth login

# self-hosted customer
orq --profile acme auth login --server https://orq.acme.internal

Manage profiles with orq auth profile: add, list, use, current, clear. orq auth profile use <name> persists the active profile, so later commands need no flag. --server sets the host to authenticate against, and is the only target flag orq setup and orq auth login need. It is stored in the session, so after login every command on that profile routes to the stored host. Override the host for a single call with --server <url> or ORQ_SERVER=<url> without changing the stored session.

Workspaces

orq workspace list         # list workspaces available to the active identity
orq workspace use <key>    # switch active workspace (persists in the session)
orq status                 # active user, workspace, project, and credential

Projects

orq projects list                # projects in the active workspace
orq projects use <project>       # select the active project by id, key, or name
orq projects use --clear         # unset it
orq switch [workspace] [project] # both selections in one command

Selecting a project exchanges the session token for one scoped to that project, so reads and creates are both narrowed with no per-command flag: orq agents list returns only that project’s Agents, and orq agents create lands there. --project <id|key|name> (env ORQ_PROJECT) does the same for a single call without changing the session. Switching workspaces clears the active project.

Diagnostics

orq doctor
orq doctor -o json         # machine-readable
orq doctor --fix           # tighten permissions on credential files
orq doctor --report        # print a pre-filled GitHub issue URL

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, reachability probes against each endpoint, and the version of the installed Orq Skills bundle.

Update

orq update                 # replace the binary using whichever method installed it
orq update --check         # report the available version, change nothing

The CLI checks its own version at most once a day and prints a notice when a newer release is available. ORQ_NO_UPDATE_CHECK suppresses both.

Output formats

Commands print a table at a terminal and TOON (Token-Oriented Object Notation), a compact format for agents, when piped. Switch the format per call or persist a new default.

orq agents list                             # table at a terminal, TOON when piped
orq agents list --output-format json        # JSON
orq agents list -o yaml                     # json, yaml, toon, or table
orq agents list --columns id,display_name   # pick table columns
orq agents list -j 'data[].display_name'    # JMESPath query

Persist a new default with orq default-format [json|yaml|toon|table]; run it bare to show the current default. -o json output on stdout is the only stable machine contract; its shape follows the API response behind the command. Add --raw to pipe a single field into another command: it prints a string or a list of scalars unquoted, one per line.

orq agents list -j 'data[].display_name' --raw | sort

Each of these flags is also an environment variable; see Global flags.

Global flags

Every command takes these, and each one has an environment variable so a shell or a CI job can set it once.

Flag	Env var	Purpose
`--profile <name>`	`ORQ_PROFILE`	Credential profile to authenticate with
`--server <url>`	`ORQ_SERVER`	API base URL
`--workspace <key>`	`ORQ_WORKSPACE`	Run this call against another workspace (never combined with `--profile`)
`--project <id\|key\|name>`	`ORQ_PROJECT`	Run this call against another project (never combined with `--profile`)
`-o, --output-format <format>`	`ORQ_OUTPUT_FORMAT`	`json`, `yaml`, `toon`, or `table`
`--columns <a,b>`	`ORQ_COLUMNS`	Columns to show in table output
`-j, --jmespath <expr>`	`ORQ_JMESPATH`	Filter or project the result
`--raw`	`ORQ_RAW`	Print scalars unquoted, one per line
`--no-input`	`ORQ_NO_INPUT`	Never prompt; fail instead of asking
`--no-color`	`ORQ_NO_COLOR`	Disable colored output (`NO_COLOR` is also honored)
`--verbose`	`ORQ_VERBOSE`	Verbose log output

Boolean env vars (ORQ_RAW, ORQ_NO_INPUT, ORQ_NO_COLOR, ORQ_VERBOSE) take 1, t, T, true, True, TRUE to turn the flag on and 0, f, F, false, False, FALSE to leave it off. Any other value, yes and on included, is treated as off without an error.

Request bodies

Commands that send a body expose every top-level body field as a typed flag, so simple requests need no JSON at all. Nested objects, arrays of objects, and polymorphic unions take a JSON string.

orq traces search --example              # print a valid example body and exit
orq traces search --from 24h --to now    # top-level fields as flags
orq agents create --from-file agent.json # read the whole body from a file
cat agent.json | orq agents create --stdin

--example on any of these commands prints a request body that command accepts, which is the fastest way to learn a shape. orq help-input documents the body syntax and orq help-config documents configuration resolution.

Scripting and CI

--no-input makes the CLI fail instead of prompting, so a stuck job errors out rather than hanging on a picker. Combine it with an API key and nothing needs a browser.

export ORQ_API_KEY=sk_live_...
export ORQ_NO_INPUT=1

orq setup --no-input --capability gateway --capability skills
orq launch claude -p "triage the failed traces from the last hour"
orq traces search --from 24h --to now -o json -j 'data[].id' --raw
orq datasets delete <id> --force

Generated delete commands prompt at a terminal and refuse to run without one. --force skips the prompt.

Relative dates

Time filters accept relative values, so yesterday’s traces or the last week’s spend are one flag away.

orq traces search --from now-24h --to now --limit 5
orq traces search --from 7d --to now --limit 50
orq traces search --from 2026-09-01 --to now

Time-scoped commands (traces search, traces query-oql, traces aggregate, the logs queries, and reporting query) default to the last 7 days when neither --from nor --to is given. Every timestamp flag accepts a relative duration read as “ago” (24h, 7d, 2w, 30m), an anchored value (now, now-24h, now+1h), a date or date and time read as UTC (2026-08-31, 2026-08-31 14:00:00), or RFC 3339. A day is 24 hours and a week is 168 hours.

Reading a conversation

orq traces conversation <trace-id> [span-id], or orq traces conv, renders the conversation recorded in a Trace as readable text. Chat Completions, Responses, and OpenTelemetry GenAI payloads are normalized into one list of messages, tool calls, and reasoning.

orq traces conversation <trace-id>                    # XML render of the newest conversational span
orq traces conv <trace-id> -o markdown                # xml, markdown, json, yaml, or toon
orq traces conv <trace-id> -i user,assistant          # roles: system, user, assistant, tool, reasoning
orq traces conv <trace-id> --match "refund"           # keep messages whose text, values, or tool calls match
orq traces conv <trace-id> --spans                    # list the trace's spans and which one was read

--slice selects messages by index and --match is a case-insensitive regex. --spans shows each span with its turn count, why it was passed over, and the id to pass as the second argument to read a different one. Evaluator spans are skipped so a judge’s conversation is never returned in place of the one it judged. The xml render escapes framing, so it is the one to trust when a span’s own text may imitate the surrounding structure. -o table is refused.

Command reference

Verified against CLI 8.6.7, plus the traces thread → traces conversation rename in the release after it. Run orq version to see the installed version and the Orq.ai API version it was built against.

Built-in commands

Command	Purpose
`orq setup`	Sign in, create a project-scoped API key, wire coding agents
`orq connect [agent...] [capability...]`	Wire coding agents permanently (`--status`, `--dry-run`)
`orq disconnect [agent...] [capability...]`	Remove what `connect` wrote
`orq launch <agent>`	Launch a coding agent through the AI Gateway for one session
`orq status`	Show active user, workspace, project, and credential (alias: `orq whoami`)
`orq switch [workspace] [project]`	Switch active workspace and project
`orq update`	Update the binary to the latest release (`--check` reports only)
`orq orqi [prompt]`	Run orqi, the Orq.ai terminal assistant, installing it on first use
`orq auth login`	OAuth device login
`orq auth logout`	Revoke refresh token, clear local session
`orq auth whoami`	Show the authenticated user and workspace
`orq auth profile add <name> --api-key-file <file>`	Save an API key profile
`orq auth sessions`	List saved browser logins by host
`orq auth profile list`, `use`, `current`, `clear`	List, switch, show, or unset the active profile
`orq workspace list`	List workspaces
`orq workspace use <key>`	Switch active workspace
`orq projects list`	List projects in the active workspace
`orq projects use [project]`	Switch active project (`--clear` unsets it)
`orq doctor`	Diagnose config, auth, reachability (`--fix`, `--report`)
`orq request <method> <path>`	Raw API escape hatch (uses configured auth)
`orq server list`, `current`, `set`, `use`, `clear`	Show, persist, or clear the API server default
`orq completion bash\|zsh\|fish\|powershell`	Generate shell completions
`orq default-format [json\|yaml\|toon\|table]`	Show or persist the default output format

Resource commands

Command groups:

Group	Commands
Get started	`auth`, `setup`, `connect`, `disconnect`, `launch`, `orqi`, `status`, `switch`, `doctor`, `update`
AI Gateway	`budgets`, `chat`, `chunking`, `completions`, `embeddings`, `guardrail-rules`, `images`, `mcp-gateways`, `mcp-servers`, `model-catalog`, `models`, `moderations`, `ocr`, `pii`, `policies`, `rerank`, `responses`, `routing-rules`, `smart-routers`, `speech`, `transcriptions`, `translations`
Observability	`alerts`, `feedback`, `identities`, `logs`, `notifiers`, `traces`
Managed agents	`agents`, `agents-responses`, `deployments`, `knowledge-bases`, `memory-stores`, `prompts`, `schedules`, `skills`, `tools`
Optimization	`annotation-queues`, `datasets`, `evals`, `human-review-sets`
Administration	`api-keys`, `files`, `management-keys`, `projects`, `reporting`, `webhooks`, `workspace`, `workspace-security`, `workspace-settings`
Utilities	`completion`, `default-format`, `help-config`, `help-input`, `man-pages`, `request`, `server`, `version`

The table below covers the most used groups. Use --help on any group for the full surface (inputs, body fields, examples):

Command	Subcommands
`orq agents`	`create`, `delete`, `get-response`, `invoke`, `list`, `retrieve`, `run`, `stream`, `stream-run`, `update`
`orq agents-responses`	`create`
`orq alerts`	`create`, `delete`, `get`, `list`, `list-trigger-events`, `list-triggers`, `update`
`orq annotation-queues`	`add-items`, `clear`, `create`, `delete`, `get`, `get-item`, `list`, `query-items`, `remove-items`, `update`
`orq api-keys`	`create`, `delete`, `get`, `list`, `list-capabilities`, `update`
`orq budgets`	`create`, `delete`, `get`, `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`, `get`, `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 logs`	`aggregate`, `get`, `get-context`, `get-patterns`, `list-facet-values`, `list-facets`, `list-fields`, `list-trace`, `query`, `search`
`orq knowledge-bases`	`create`, `create-chunks`, `create-datasource`, `delete`, `delete-chunk`, `delete-chunks`, `delete-datasource`, `get-chunks-count`, `list`, `list-chunks`, `list-chunks-paginated`, `list-datasources`, `retrieve`, `retrieve-chunk`, `retrieve-datasource`, `retrieve-file-url`, `retrieve-processing-status`, `search`, `toggle-chunk`, `update`, `update-chunk`, `update-datasource`
`orq management-keys`	`create`, `delete`, `get`, `list`, `list-capabilities`, `update`
`orq mcp-gateways`	`create`, `delete`, `list`, `list-tools`, `retrieve`, `update`
`orq mcp-servers`	`create`, `delete`, `list`, `retrieve`, `sync`, `test-tool`, `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 model-catalog`	`get`, `list`, `list-offerings`
`orq models`	`azure-foundry-deployments`, `create`, `create-aws-bedrock`, `create-openai-like`, `create-vertex`, `delete`, `disable`, `enable`, `import-litellm`, `list`, `list-litellm`, `update`, `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 smart-routers`	`create`, `delete`, `get`, `list`, `update`
`orq speech`	`create`
`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`, `conversation` (alias `conv`), `insights-service-*` (analysis runs, clusters, insights)
`orq transcriptions`	`create`
`orq translations`	`create`
`orq webhooks`	`count`, `create`, `delete`, `generate-secret`, `get`, `list`, `query`, `update`
`orq workspace-security`	`add-ip-range`, `create-domain`, `delete-domain`, `delete-ip-range`, `get-ip-allowlist`, `list-domains`, `update-ip-allowlist`, `verify-domain`
`orq workspace-settings`	`get`, `update`

Orq SDK

Terminal & Agents

Terraform

Platform APIs

Management APIs

GitHub

orq-cli

Installation

Quick start

Coding agents

Authentication

Profiles

Workspaces

Projects

Diagnostics

Update

Output formats

Global flags

Request bodies

Scripting and CI

Relative dates

Reading a conversation

Command reference

Built-in commands

Resource commands

​GitHub

orq-cli

​Installation

​Quick start

​Coding agents

​Authentication

​Profiles

​Workspaces

​Projects

​Diagnostics

​Update

​Output formats

​Global flags

​Request bodies

​Scripting and CI

​Relative dates

​Reading a conversation

​Command reference

​Built-in commands

​Resource commands

GitHub

Installation

Quick start

Coding agents

Authentication

Profiles

Workspaces

Projects

Diagnostics

Update

Output formats

Global flags

Request bodies

Scripting and CI

Relative dates

Reading a conversation

Command reference

Built-in commands

Resource commands