> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Orq CLI
> Install and authenticate the Orq.ai CLI. Manage prompts, agents, deployments, knowledge bases, evaluators, and the rest of the Orq.ai platform from a terminal, CI, or scripts.
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
## Installation
```bash npm theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm install -g @orq-ai/cli
```
```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://github.com/orq-ai/orq-cli/releases).
## Authentication
The CLI supports two auth methods. Both respect `--profile ` to keep multiple identities (personal account, CI, self-hosted customer) side by side.
```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`.
```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
export ORQ_API_KEY=sk_live_...
orq agents list
```
Get an API key from **Organization > [API Keys](/docs/ai-studio/organization/api-keys)**. For multiple keys, save each one to a profile:
```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq auth add-profile apikey ci
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:
```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
unset ORQ_API_KEY
```
### Profiles
Every command accepts `--profile ` (or the `ORQ_PROFILE` env var). Each profile has its own session file at `~/.orq/sessions/.json` and its own API key credentials in `~/.orq/credentials.json`. The default profile is `default`.
```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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 ` or `ORQ_SERVER=` without changing the stored session.
## Quick start
With the CLI installed and authenticated, run a resource command to confirm everything works:
```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq whoami # verify identity
orq agents list # example resource command
```
## Diagnostics
```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.
```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 `.
## Workspaces
```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq workspace list # list workspaces available to the active identity
orq workspace use # 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 ` | Save an API key profile |
| `orq auth list-profiles` | List configured credential profiles |
| `orq workspace list` | List workspaces |
| `orq workspace use ` | Switch active workspace |
| `orq doctor` | Diagnose config, auth, reachability |
| `orq request ` | 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 ` | 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` |