> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oqoqo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Install and update the oqoqo CLI, sign in, pick a project, and learn the flags, output, exit codes, and rules that every command shares.

`oqoqo` is the command-line client for Oqoqo. Use it in your terminal, in scripts and CI, or from an AI assistant to define tasks, build treatments, run experiments, and read results. Each command group has its own page, listed in the [command index](#command-index).

Every command except `login`, `logout`, `version`, `upgrade`, `schema`, and `acp` has a matching tool in the [Plugin (MCP) reference](https://docs.oqoqo.ai/mcp-server/overview.md), with the same inputs and result fields. New to the CLI? Start with [Use the CLI](https://docs.oqoqo.ai/operate/cli.md).

## Install

Run the install script on macOS or Linux (arm64 or x64):

```bash theme={null}
curl -fsSL https://oqoqo.ai/install | sh
```

The script installs `oqoqo` in `~/.local/bin` when that folder is on your `PATH`, and in `~/.oqoqo/bin` otherwise, so you don't need `sudo`. To choose another folder, set `OQOQO_INSTALL_DIR` before you run it. The dashboard shows the same command under **Automate → Oqoqo CLI**.

## Keep the CLI current

To install the latest release right away, run [`oqoqo upgrade`](https://docs.oqoqo.ai/cli/sign-in#oqoqo-upgrade). It works without a sign-in.

```bash theme={null}
oqoqo upgrade
oqoqo upgrade --check
```

### Background updates

An installed CLI also keeps itself current. After a command, it checks for a new release in the background, at most once an hour, and installs any release it finds. The command you ran stays on its release, and your next command uses the new one.

Background updates are off in the cases below. To see whether they're on, run [`oqoqo version`](https://docs.oqoqo.ai/cli/sign-in#oqoqo-version) and read `autoUpdate`.

| Condition | Checks for a release | Installs in the background | Prints update notices |
| - | - | - | - |
| `OQOQO_DISABLE_AUTOUPDATE` is set | Yes | No | Yes |
| `OQOQO_NO_UPDATE_NOTIFIER` is set | No | No | No |
| `CI` is set | No | No | No |
| `OQOQO_API_KEY` is set | No | No | No |
| The CLI runs from source, not from an installed binary | No | No | No |

`OQOQO_DISABLE_AUTOUPDATE`, `OQOQO_NO_UPDATE_NOTIFIER`, and `CI` count as set unless their value is empty, `0`, `false`, or `no`. `oqoqo upgrade` works in every one of these cases.

### Update notices

After a successful command in a terminal, the CLI can print one line on stderr that names the installed release and the newer one:

```text theme={null}
Updated oqoqo 2026.11.10.1 -> 2026.11.12.1 in the background.
A new oqoqo release is available: 2026.11.10.1 -> 2026.11.12.1. Run `oqoqo upgrade` to update.
```

The first line appears after a background install. The second appears when `OQOQO_DISABLE_AUTOUPDATE` is set or a background install of that release failed. There's no notice with `--output json` or `--quiet`, outside a terminal, after a failed command, or after `upgrade`, `version`, `schema`, or `help`.

### When Oqoqo refuses an old release

When Oqoqo no longer accepts your installed release, any command that contacts Oqoqo changes nothing, exits with code `4`, and prints:

```text theme={null}
oqoqo: This oqoqo release is older than the server supports: run `oqoqo upgrade`, then retry.
```

With `--output json`, `error.code` is `client_update_required`. Run `oqoqo upgrade`, then run the command again. `oqoqo upgrade`, `oqoqo version`, and `oqoqo schema` don't contact the Oqoqo API, so they keep working.

A [custom agent](https://docs.oqoqo.ai/setup/custom-agents.md) that downloads a pinned CLI build doesn't pick up new releases. To update it, copy a current `url` and `sha256` into it, save, and test it again, as [Run Ask Oqo as a custom agent](https://docs.oqoqo.ai/guides/ask-oqo-custom-agent.md) shows.

## Sign in

To sign in, run [`oqoqo login`](https://docs.oqoqo.ai/cli/sign-in#oqoqo-login). It opens Oqoqo sign-in in your browser and shows a confirmation code. When you confirm the code in the browser, the CLI saves your sign-in and uses it for every command.

```bash theme={null}
oqoqo login
oqoqo whoami
```

The CLI keeps your sign-in and saved project in `~/.config/oqoqo`, or in `$XDG_CONFIG_HOME/oqoqo` when that variable is set. [`oqoqo logout`](https://docs.oqoqo.ai/cli/sign-in#oqoqo-logout) removes both.

### Use an API key

Use a personal API key where nobody can sign in through a browser, such as a CI job or the machine an agent runs in.

1. In the dashboard, open **Profile → API keys** and [create a key](https://docs.oqoqo.ai/setup/profile.md#api-keys).
2. Store the key as a secret, and set it as `OQOQO_API_KEY` where the CLI runs.

```bash theme={null}
export OQOQO_API_KEY="$OQOQO_PERSONAL_KEY"
oqoqo whoami
```

While `OQOQO_API_KEY` is set:

* Every command sends the key instead of your saved sign-in, acting as you in the key's organization. `oqoqo whoami` reports `credential` as `api_key`.
* `oqoqo login` refuses to sign in, and `oqoqo logout` removes only the saved sign-in.
* The CLI doesn't check for or install updates; run `oqoqo upgrade` yourself.
* A CI job has no saved project, so pass `--project-id` on every command.

A key that isn't valid, or that you revoked, fails with an auth error (exit code `3`) that points to the **API keys** page. Only personal keys work: organization API keys can't use the CLI, and the plugin signs in with OAuth instead.

## Choose a project

Most commands work in one project. The CLI picks that project in this order:

1. The `--project-id` flag on the command. It applies to that one call and is never saved.
2. The project you saved with [`oqoqo projects use`](https://docs.oqoqo.ai/cli/projects#oqoqo-projects-use).
3. A project that Oqoqo chooses for you when you saved none.

```bash theme={null}
oqoqo projects list
oqoqo projects use prj_4d7a20c5
oqoqo experiments list --project-id prj_9b13e6f2
```

[`oqoqo projects current`](https://docs.oqoqo.ai/cli/projects#oqoqo-projects-current) shows the project and where it came from: `explicit`, `preferred`, or `fallback`. The saved project belongs to the organization you signed in to; if you can no longer open it, the CLI forgets it and Oqoqo chooses again.

## Global flags

Every command takes these flags. Put flags after the command words, as in `oqoqo experiments list --output json`.

| Flag | Type | Default | Description |
| - | - | - | - |
| `--output`, `-o` | `text`, `json` | `text` | Output format. `json` prints one JSON envelope on stdout. See [Output](#output). |
| `--quiet`, `-q` | boolean | `false` | Hide progress messages on stderr. Required prompts and sign-in links still print. |
| `--verbose`, `-v` | boolean | `false` | Print diagnostic logs on stderr, like `OQOQO_DEBUG=1`. Logs never contain tokens or keys. |
| `--help`, `-h` | boolean | `false` | Show help for the command, like `oqoqo help <command>`. |
| `--expected-organization-id` | string | | Run only in this organization. Read the ID from `oqoqo whoami`. If your sign-in now uses another organization, the command changes nothing and fails with `organization_scope_changed`. |
| `--project-id` | string | The saved project | On commands that work in a project: run this one command in this `prj_` project. It never changes the saved project. |

`oqoqo --help` lists every command, and `oqoqo --version` prints the version and channel on one line.

## Output

By default, a command prints readable text on stdout, and sends progress messages, prompts, and errors to stderr. A script that reads stdout gets only the result.

With `--output json`, stdout holds exactly one JSON object, whether the command succeeds or fails. Progress messages and prompts stay on stderr. A success looks like this:

```json theme={null}
{
  "ok": true,
  "command": "schedules get",
  "data": {
    "schedule": {
      "scheduleId": "sch_c0a9f311",
      "name": "Nightly checkout",
      "status": "active",
      "lockVersion": 3
    }
  }
}
```

`data` holds the command's result, with the same fields as the matching plugin tool. The example shows only some of them; for a command's exact shape, run `oqoqo schema <command>`.

A failure looks like this:

```json theme={null}
{
  "ok": false,
  "command": "schedules pause",
  "error": {
    "code": "schedule_changed",
    "message": "This schedule changed after you read it (lock version is now 4). Read it again, then retry.",
    "details": { "lockVersion": 4 }
  }
}
```

| Field | Description |
| - | - |
| `error.code` | A stable code to branch on: Oqoqo's own code when the server gave one, such as `schedule_changed`, or else a CLI code from [Exit codes](#exit-codes). |
| `error.message` | What went wrong and what to do next. |
| `error.details` | Only when it adds facts, such as a `setupUrl`, a record's current version, or a JSON input's validation issues. |

In text mode, an error prints on stderr as `oqoqo: <message>`, followed by one line for each simple detail, such as an ID or a link.

## Exit codes

| Code | Meaning | CLI `error.code` values |
| - | - | - |
| `0` | The command succeeded. The result can still report a failed experiment or a blocked plan. | |
| `1` | An unexpected error in the CLI, or a platform the CLI does not support. | `internal_error`, `unsupported_platform` |
| `2` | Usage error: an unknown command or flag, a missing argument, input that does not match the schema, or a destructive command without confirmation. Nothing changed. | `usage_error` |
| `3` | Auth error: you are not signed in, your sign-in expired, or Oqoqo refused your API key. | `not_logged_in`, `auth_expired`, `auth_denied` |
| `4` | Oqoqo refused or failed the request, such as a blocker, a conflict, a stale lock version, `client_update_required`, or an `experiments watch` timeout (`watch_timeout`). | `api_error`, or Oqoqo's own code |
| `5` | Network error: the CLI could not reach Oqoqo. | `network_error` |
| `6` | The command succeeded, and the result matched a flag that you set to fail on it: [`experiments watch --fail-on`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-watch) or [`experiments preflight --require-ready`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-preflight). The output is the same as for code `0`. | |

When you mistype a command, the message suggests the closest command in that group and tells you to run `oqoqo <group> --help`.

## Environment variables

| Variable | Effect |
| - | - |
| `OQOQO_API_KEY` | A personal [API key](#use-an-api-key) that every command sends instead of your saved sign-in. Also turns off [background updates](#background-updates). |
| `OQOQO_DISABLE_AUTOUPDATE` | Turns off background installs, but not checks and notices. |
| `OQOQO_NO_UPDATE_NOTIFIER` | Turns off update checks, background installs, and notices. |
| `CI` | Same as `OQOQO_NO_UPDATE_NOTIFIER`. Most CI services set it. |
| `OQOQO_DEBUG` | `1`, `true`, or `yes` prints diagnostic logs on stderr, like `--verbose`. |
| `XDG_CONFIG_HOME` | Keeps the sign-in and saved project in `$XDG_CONFIG_HOME/oqoqo` instead of `~/.config/oqoqo`. |
| `OQOQO_INSTALL_DIR` | The install script's target folder. |

## Conventions

These rules apply wherever a command needs them, and the plugin follows the same ones.

### Confirm destructive commands

A destructive command removes, cancels, replaces, or stops sharing a resource. In an interactive terminal, the CLI shows what will change and asks you to enter `y`. In non-interactive runs or with `--output json`, pass `--yes`; otherwise the CLI makes no changes and exits with code `2`.

```bash theme={null}
oqoqo schedules delete sch_c0a9f311 --lock-version 3 --yes --output json
```

`oqoqo projects delete` and `oqoqo resources delete` also support `--dry-run`, which prints affected items and blockers without modifying anything. When a blocker applies, the CLI skips confirmation and fails with an error code such as `project_deletion_blocked` or `resource_deletion_blocked`.

Commands that spend runs or publish results, such as `oqoqo experiments launch`, do not prompt unless they are also destructive. Ask Oqo still prompts for approval before running them, and each command page notes this.

### Retry safely with attempt IDs

A command that starts work takes an attempt ID: a string you choose for one intended change. After a lost response or a timeout, resend the same ID and input to get the first result back instead of doing the work twice. Reusing an ID for different input fails with a conflict, such as `launch_attempt_conflict`.

| Command | Attempt ID | Without one |
| - | - | - |
| `experiments launch`, `experiments preflight` | `launchAttemptId` in the plan | Required. |
| `experiments rerun`, `schedules launch`, `schedules create`, `schedules update`, `project ai test-agent` | `--attempt-id` | The CLI makes one and prints it on stderr, unless you pass `--quiet`. |
| `experiments clone-plan` | `--attempt-id`, written to the plan's `launchAttemptId` | The CLI makes one and puts it in the plan. |
| `experiments publish`, `experiments publications update`, `resources delete`, `evals trigger`, `insights trigger` | `--attempt-id` | A new one for each call, so pass your own to retry safely. |
| `projects create` | `--mutation-attempt-id` | Required. |
| `resources apply`, `resources bulk-apply`, `resources lifecycle` | `mutationAttemptId` in each operation | Required. |
| `uploads complete` | The `upl_` upload ID | Required. |

### Avoid overwriting other changes

A command that changes a record also takes the version you read. If the record changed since, the command fails without changing anything; read it again and retry with the new value.

| Flag or field | Read it from | Error when stale |
| - | - | - |
| `--lock-version` (schedules) | `oqoqo schedules get` | `schedule_changed` |
| `--lock-version` (public links) | `oqoqo experiments publications get` | `publication_changed` |
| `--expected-updated-at` (projects) | `oqoqo projects inspect` | `project_update_stale` |
| `--expected-updated-at` (tags) | `oqoqo tags list` | `tag_changed` |
| `expectedUpdatedAt` in an operation, `--expected-updated-at` on `uploads create` | `oqoqo catalog list --projection full` | `resource_revision_conflict` |
| `projectConfigurationRevision`, `organizationConfigurationRevision` in a launch plan | `oqoqo catalog list --kind agent --projection full`, or `oqoqo experiments preflight` | `configuration_changed` |
| `--plan-hash` | `oqoqo resources delete --dry-run` | `resource_deletion_plan_changed` |

### Page through results

Reads return bounded pages. A `--limit` above a command's maximum is capped, not refused, and each response is also capped at 20 KiB, so a page can hold fewer items than the limit.

| Read | How to continue |
| - | - |
| Lists, such as `experiments list` and `catalog list` | While `hasMore` is true, pass `nextCursor` as `--cursor`, with the same filters. In text mode, the CLI prints the next `--cursor`. |
| Byte content, such as `resources archive` and `resources inspect --view definition` | Pass the next offset as `--offset` until `eof` is true. One page holds at most 12,288 bytes. |
| Version history in `resources inspect --view versions` | While `hasMore` is true, pass `nextBeforeVersion` as `--before-version`. |
| `data query` | Send the same query again with the returned cursor in its `cursor` field. |

### Wait for long work

Launches, uploads, deletions, Evals, and Insights keep going after the command that starts them returns, so read their status until it's final. `oqoqo experiments status --wait-ms` waits in the server up to 25,000 milliseconds for a change, and [`oqoqo experiments watch`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-watch) reads until the experiment ends.

### Secrets stay in the dashboard

No command accepts OAuth grants, API keys, secret headers, secret values, or payments. When a step needs one, the command returns the exact dashboard link for it, often as `setupUrl`: open it where you're signed in, enter the value, and continue in the CLI. [`oqoqo setup links`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-setup-links) lists every machine and tool in the project that still needs a value or your account connection. The full rule is in [Secrets stay in the dashboard](https://docs.oqoqo.ai/mcp-server/overview.md#secrets-stay-in-the-dashboard).

### IDs

Commands take and return stable public IDs, and each ID starts with a prefix that names its kind, such as `prj_`, `exp_`, or `run_`. Pass an ID that a command returned; don't build one. The examples on these pages shorten IDs to keep them readable. Every prefix, its length, and where to find it are in [IDs and limits](https://docs.oqoqo.ai/reference/ids-and-limits.md).

### Read command schemas

[`oqoqo schema`](https://docs.oqoqo.ai/cli/sign-in#oqoqo-schema) lists every command, and `oqoqo schema <command>` prints that command's arguments, flags, JSON input, and output as JSON Schema. An AI assistant can read the schema instead of the help text.

## Command index

| `oqoqo` command | What it does | Plugin (MCP) tool |
| - | - | - |
| [`login`](https://docs.oqoqo.ai/cli/sign-in#oqoqo-login) | Sign in with your browser. | |
| [`whoami`](https://docs.oqoqo.ai/cli/sign-in#oqoqo-whoami) | Show who you are signed in as, and how. | [`get_identity`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#get_identity) |
| [`logout`](https://docs.oqoqo.ai/cli/sign-in#oqoqo-logout) | Remove your saved sign-in. | |
| [`version`](https://docs.oqoqo.ai/cli/sign-in#oqoqo-version) | Show the version, channel, and update setting. | |
| [`upgrade`](https://docs.oqoqo.ai/cli/sign-in#oqoqo-upgrade) | Install the latest release now. | |
| [`schema`](https://docs.oqoqo.ai/cli/sign-in#oqoqo-schema) | Print each command's JSON Schema. | |
| [`projects list`](https://docs.oqoqo.ai/cli/projects#oqoqo-projects-list) | List projects and mark the current one. | [`get_project_context`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#get_project_context) |
| [`projects current`](https://docs.oqoqo.ai/cli/projects#oqoqo-projects-current) | Show the current project and its source. | [`get_project_context`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#get_project_context) |
| [`projects use`](https://docs.oqoqo.ai/cli/projects#oqoqo-projects-use) | Save a project for later commands. | [`get_project_context`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#get_project_context) |
| [`projects inspect`](https://docs.oqoqo.ai/cli/projects#oqoqo-projects-inspect) | Show one project. | [`get_project_context`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#get_project_context) |
| [`projects create`](https://docs.oqoqo.ai/cli/projects#oqoqo-projects-create) | Create a project. | [`manage_project`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#manage_project) |
| [`projects update`](https://docs.oqoqo.ai/cli/projects#oqoqo-projects-update) | Rename a project. | [`manage_project`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#manage_project) |
| [`projects delete`](https://docs.oqoqo.ai/cli/projects#oqoqo-projects-delete) | Permanently delete a project. | [`preview_delete_project`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#preview_delete_project), [`delete_project`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#delete_project) |
| [`catalog list`](https://docs.oqoqo.ai/cli/catalog#oqoqo-catalog-list) | Search every kind of project resource. | [`inspect_catalog`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#inspect_catalog) |
| [`github browse`](https://docs.oqoqo.ai/cli/catalog#oqoqo-github-browse) | Find a public GitHub source to import. | [`browse_github_source`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#browse_github_source) |
| [`resources inspect`](https://docs.oqoqo.ai/cli/catalog#oqoqo-resources-inspect) | Read a resource's detail, versions, or definition. | [`inspect_resource`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#inspect_resource) |
| [`resources impact`](https://docs.oqoqo.ai/cli/catalog#oqoqo-resources-impact) | Check what depends on a resource. | [`inspect_resource_impact`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#inspect_resource_impact) |
| [`resources apply`](https://docs.oqoqo.ai/cli/catalog#oqoqo-resources-apply) | Create or update one resource from JSON. | [`author_resource`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#author_resource) |
| [`resources bulk-apply`](https://docs.oqoqo.ai/cli/catalog#oqoqo-resources-bulk-apply) | Apply up to 20 resource operations. | [`bulk_author_resources`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#bulk_author_resources) |
| [`resources lifecycle`](https://docs.oqoqo.ai/cli/catalog#oqoqo-resources-lifecycle) | Set official versions and defaults, or sync from GitHub. | [`manage_resource`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#manage_resource) |
| [`resources archive`](https://docs.oqoqo.ai/cli/catalog#oqoqo-resources-archive) | Download a file or skill as a ZIP. | [`download_resource_archive`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#download_resource_archive) |
| [`uploads create`](https://docs.oqoqo.ai/cli/catalog#oqoqo-uploads-create) | Upload a folder or ZIP as a file, skills, or tasks. | [`create_upload`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#create_upload) |
| [`uploads get`](https://docs.oqoqo.ai/cli/catalog#oqoqo-uploads-get) | Read an upload's status and result. | [`get_upload`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#get_upload) |
| [`uploads complete`](https://docs.oqoqo.ai/cli/catalog#oqoqo-uploads-complete) | Check and apply an uploaded archive. | [`complete_upload`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#complete_upload) |
| [`uploads cancel`](https://docs.oqoqo.ai/cli/catalog#oqoqo-uploads-cancel) | Cancel an open upload. | [`cancel_upload`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#cancel_upload) |
| [`resources delete`](https://docs.oqoqo.ai/cli/catalog#oqoqo-resources-delete) | Permanently delete experiments and resources. | [`preview_delete_resources`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#preview_delete_resources), [`delete_resources`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#delete_resources) |
| [`deletions status`](https://docs.oqoqo.ai/cli/catalog#oqoqo-deletions-status) | Read a deletion's status. | [`get_resource_deletion`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#get_resource_deletion) |
| [`experiments preflight`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-preflight) | Check a launch plan without launching. | [`preflight_experiment`](https://docs.oqoqo.ai/mcp-server/experiments#preflight_experiment) |
| [`experiments launch`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-launch) | Launch an experiment from a plan. | [`launch_experiment`](https://docs.oqoqo.ai/mcp-server/experiments#launch_experiment) |
| [`experiments status`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-status) | Read an experiment's progress once. | [`get_experiment_status`](https://docs.oqoqo.ai/mcp-server/experiments#get_experiment_status), [`get_launch_status`](https://docs.oqoqo.ai/mcp-server/experiments#get_launch_status) |
| [`experiments watch`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-watch) | Wait until an experiment ends. | [`get_experiment_status`](https://docs.oqoqo.ai/mcp-server/experiments#get_experiment_status), [`get_launch_status`](https://docs.oqoqo.ai/mcp-server/experiments#get_launch_status) |
| [`experiments list`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-list) | List and filter experiments. | [`list_experiments`](https://docs.oqoqo.ai/mcp-server/experiments#list_experiments) |
| [`experiments get`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-get) | Read an experiment's progress, lineage, and runs used. | [`get_experiment`](https://docs.oqoqo.ai/mcp-server/experiments#get_experiment) |
| [`experiments rename`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-rename) | Rename an experiment. | [`rename_experiment`](https://docs.oqoqo.ai/mcp-server/experiments#rename_experiment) |
| [`experiments brief`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-brief) | Read an experiment's Brief: its differences and the frictions seen with them. | [`get_experiment_brief`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#get_experiment_brief) |
| [`experiments clone-plan`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-clone-plan) | Get a launch plan from an experiment. | [`get_experiment_plan`](https://docs.oqoqo.ai/mcp-server/experiments#get_experiment_plan) |
| [`experiments rerun`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-rerun) | Launch a finished experiment again. | [`rerun_experiment`](https://docs.oqoqo.ai/mcp-server/experiments#rerun_experiment) |
| [`experiments cancel`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-cancel) | Cancel an experiment or one run. | [`cancel_experiment`](https://docs.oqoqo.ai/mcp-server/experiments#cancel_experiment) |
| [`experiments publish`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-publish) | Publish a completed experiment at a public link. | [`publish_experiment`](https://docs.oqoqo.ai/mcp-server/experiments#publish_experiment) |
| [`experiments publications list`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-publications-list) | List your organization's public links. | [`list_experiment_publications`](https://docs.oqoqo.ai/mcp-server/experiments#list_experiment_publications) |
| [`experiments publications get`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-publications-get) | Read one public link. | [`get_experiment_publication`](https://docs.oqoqo.ai/mcp-server/experiments#get_experiment_publication) |
| [`experiments publications update`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-publications-update) | Publish the latest results to a public link. | [`update_experiment_publication`](https://docs.oqoqo.ai/mcp-server/experiments#update_experiment_publication) |
| [`experiments publications unpublish`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-publications-unpublish) | Stop sharing a public link. | [`unpublish_experiment`](https://docs.oqoqo.ai/mcp-server/experiments#unpublish_experiment) |
| [`gallery get`](https://docs.oqoqo.ai/cli/experiments#oqoqo-gallery-get) | Read results from a public link. | [`get_public_experiment`](https://docs.oqoqo.ai/mcp-server/experiments#get_public_experiment) |
| [`schedules preview`](https://docs.oqoqo.ai/cli/schedules#oqoqo-schedules-preview) | Preview a schedule's launches and runs. | [`preview_schedule`](https://docs.oqoqo.ai/mcp-server/schedules#preview_schedule) |
| [`schedules create`](https://docs.oqoqo.ai/cli/schedules#oqoqo-schedules-create) | Schedule a finished experiment. | [`manage_schedule`](https://docs.oqoqo.ai/mcp-server/schedules#manage_schedule) |
| [`schedules list`](https://docs.oqoqo.ai/cli/schedules#oqoqo-schedules-list) | List the project's schedules. | [`list_schedules`](https://docs.oqoqo.ai/mcp-server/schedules#list_schedules) |
| [`schedules get`](https://docs.oqoqo.ai/cli/schedules#oqoqo-schedules-get) | Read one schedule. | [`get_schedule`](https://docs.oqoqo.ai/mcp-server/schedules#get_schedule) |
| [`schedules update`](https://docs.oqoqo.ai/cli/schedules#oqoqo-schedules-update) | Change a schedule's name, cadence, or experiment. | [`manage_schedule`](https://docs.oqoqo.ai/mcp-server/schedules#manage_schedule) |
| [`schedules pause`](https://docs.oqoqo.ai/cli/schedules#oqoqo-schedules-pause) | Pause a schedule. | [`manage_schedule`](https://docs.oqoqo.ai/mcp-server/schedules#manage_schedule) |
| [`schedules resume`](https://docs.oqoqo.ai/cli/schedules#oqoqo-schedules-resume) | Resume a paused schedule. | [`manage_schedule`](https://docs.oqoqo.ai/mcp-server/schedules#manage_schedule) |
| [`schedules launch`](https://docs.oqoqo.ai/cli/schedules#oqoqo-schedules-launch) | Launch a schedule's experiment now. | [`rerun_experiment`](https://docs.oqoqo.ai/mcp-server/experiments#rerun_experiment) |
| [`schedules delete`](https://docs.oqoqo.ai/cli/schedules#oqoqo-schedules-delete) | Delete a schedule. | [`delete_schedule`](https://docs.oqoqo.ai/mcp-server/schedules#delete_schedule) |
| [`runs list`](https://docs.oqoqo.ai/cli/runs#oqoqo-runs-list) | List run results. | [`list_runs`](https://docs.oqoqo.ai/mcp-server/runs-and-results#list_runs) |
| [`runs profile`](https://docs.oqoqo.ai/cli/runs#oqoqo-runs-profile) | Show a run's treatment use, tool calls, and time. | [`get_run_profile`](https://docs.oqoqo.ai/mcp-server/runs-and-results#get_run_profile) |
| [`runs trajectory`](https://docs.oqoqo.ai/cli/runs#oqoqo-runs-trajectory) | Page a run's steps. | [`get_run_trajectory`](https://docs.oqoqo.ai/mcp-server/runs-and-results#get_run_trajectory) |
| [`runs transcript`](https://docs.oqoqo.ai/cli/runs#oqoqo-runs-transcript) | Read a run's original transcript. | [`get_run_transcript`](https://docs.oqoqo.ai/mcp-server/runs-and-results#get_run_transcript) |
| [`runs output`](https://docs.oqoqo.ai/cli/runs#oqoqo-runs-output) | Read a run's output files and diffs. | [`get_run_output`](https://docs.oqoqo.ai/mcp-server/runs-and-results#get_run_output) |
| [`results analyze`](https://docs.oqoqo.ai/cli/runs#oqoqo-results-analyze) | Summarize, compare, and search results. | [`analyze_results`](https://docs.oqoqo.ai/mcp-server/runs-and-results#analyze_results) |
| [`frictions list`](https://docs.oqoqo.ai/cli/frictions#oqoqo-frictions-list) | Rank the project's frictions. | [`list_frictions`](https://docs.oqoqo.ai/mcp-server/frictions#list_frictions) |
| [`frictions get`](https://docs.oqoqo.ai/cli/frictions#oqoqo-frictions-get) | Read one friction. | [`get_friction`](https://docs.oqoqo.ai/mcp-server/frictions#get_friction) |
| [`evals preview`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-evals-preview) | Check which runs can get Evals. | [`preview_evals`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#preview_evals) |
| [`evals trigger`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-evals-trigger) | Run Evals on an experiment's runs. | [`trigger_evals`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#trigger_evals) |
| [`evals list`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-evals-list) | List an experiment's Evals attempts. | [`list_evals`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#list_evals) |
| [`evals get`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-evals-get) | Read the results of an Evals attempt. | [`get_evals_results`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#get_evals_results) |
| [`evals compare`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-evals-compare) | Compare an experiment's treatments and agents. | [`get_evals_comparisons`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#get_evals_comparisons) |
| [`insights preview`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-insights-preview) | Check whether Insights can run. | [`preview_insights`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#preview_insights) |
| [`insights trigger`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-insights-trigger) | Run Insights on an experiment's runs. | [`trigger_insights`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#trigger_insights) |
| [`insights list`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-insights-list) | List an experiment's Insights attempts. | [`list_insights`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#list_insights) |
| [`insights get`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-insights-get) | Read the results of an Insights attempt. | [`get_insights_results`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#get_insights_results) |
| [`tags list`](https://docs.oqoqo.ai/cli/tags#oqoqo-tags-list) | List the project's tags. | [`list_tags`](https://docs.oqoqo.ai/mcp-server/tags-and-data#list_tags) |
| [`tags add`](https://docs.oqoqo.ai/cli/tags#oqoqo-tags-add) | Add tags to records. | [`update_tags`](https://docs.oqoqo.ai/mcp-server/tags-and-data#update_tags) |
| [`tags remove`](https://docs.oqoqo.ai/cli/tags#oqoqo-tags-remove) | Remove tags from records. | [`update_tags`](https://docs.oqoqo.ai/mcp-server/tags-and-data#update_tags) |
| [`tags rename`](https://docs.oqoqo.ai/cli/tags#oqoqo-tags-rename) | Rename a tag. | [`rename_tag`](https://docs.oqoqo.ai/mcp-server/tags-and-data#rename_tag) |
| [`tags delete`](https://docs.oqoqo.ai/cli/tags#oqoqo-tags-delete) | Delete a tag from every record. | [`delete_tag`](https://docs.oqoqo.ai/mcp-server/tags-and-data#delete_tag) |
| [`data describe`](https://docs.oqoqo.ai/cli/data#oqoqo-data-describe) | List the datasets and fields you can query. | [`inspect_data_model`](https://docs.oqoqo.ai/mcp-server/tags-and-data#inspect_data_model) |
| [`data query`](https://docs.oqoqo.ai/cli/data#oqoqo-data-query) | Query, group, and count Oqoqo data. | [`query_data`](https://docs.oqoqo.ai/mcp-server/tags-and-data#query_data) |
| [`project ai inspect`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-project-ai-inspect) | Read agents, providers, models, and Oqoqo AI defaults. | [`inspect_project_ai`](https://docs.oqoqo.ai/mcp-server/agents-and-setup#inspect_project_ai) |
| [`project ai apply`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-project-ai-apply) | Change agents, models, custom agents, and Oqoqo AI defaults. | [`manage_project_ai`](https://docs.oqoqo.ai/mcp-server/agents-and-setup#manage_project_ai) |
| [`project ai delete`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-project-ai-delete) | Remove a custom agent or a provider connection. | [`delete_project_ai`](https://docs.oqoqo.ai/mcp-server/agents-and-setup#delete_project_ai) |
| [`project ai test-agent`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-project-ai-test-agent) | Test a custom agent with one run. | [`test_custom_agent`](https://docs.oqoqo.ai/mcp-server/agents-and-setup#test_custom_agent) |
| [`setup links`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-setup-links) | List web links for values you enter in the dashboard. | [`get_setup_links`](https://docs.oqoqo.ai/mcp-server/agents-and-setup#get_setup_links) |
| [`mcp accounts inspect`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-mcp-accounts-inspect) | Check your connection to an MCP server. | [`inspect_mcp_account`](https://docs.oqoqo.ai/mcp-server/agents-and-setup#inspect_mcp_account) |
| [`mcp accounts detect-auth`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-mcp-accounts-detect-auth) | Detect how an MCP server signs in. | [`detect_mcp_auth_mode`](https://docs.oqoqo.ai/mcp-server/agents-and-setup#detect_mcp_auth_mode) |
| [`mcp tools list`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-mcp-tools-list) | List an MCP server's tools. | [`list_mcp_server_tools`](https://docs.oqoqo.ai/mcp-server/agents-and-setup#list_mcp_server_tools) |
| [`mcp tools refresh`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-mcp-tools-refresh) | Check an MCP server's tools again. | [`refresh_mcp_server_tools`](https://docs.oqoqo.ai/mcp-server/agents-and-setup#refresh_mcp_server_tools) |
| [`quota inspect`](https://docs.oqoqo.ai/cli/billing-and-notifications#oqoqo-quota-inspect) | Show the run balance. | [`inspect_quota`](https://docs.oqoqo.ai/mcp-server/quota-and-notifications#inspect_quota) |
| [`quota ledger`](https://docs.oqoqo.ai/cli/billing-and-notifications#oqoqo-quota-ledger) | List run balance history. | [`list_quota_ledger`](https://docs.oqoqo.ai/mcp-server/quota-and-notifications#list_quota_ledger) |
| [`notifications list`](https://docs.oqoqo.ai/cli/billing-and-notifications#oqoqo-notifications-list) | List your notifications. | [`list_notifications`](https://docs.oqoqo.ai/mcp-server/quota-and-notifications#list_notifications) |
| [`notifications acknowledge`](https://docs.oqoqo.ai/cli/billing-and-notifications#oqoqo-notifications-acknowledge) | Mark notifications as read. | [`acknowledge_notifications`](https://docs.oqoqo.ai/mcp-server/quota-and-notifications#acknowledge_notifications) |
| [`notifications preferences`](https://docs.oqoqo.ai/cli/billing-and-notifications#oqoqo-notifications-preferences) | Show your notification preferences. | [`inspect_notification_preferences`](https://docs.oqoqo.ai/mcp-server/quota-and-notifications#inspect_notification_preferences) |
| [`notifications preferences update`](https://docs.oqoqo.ai/cli/billing-and-notifications#oqoqo-notifications-preferences-update) | Change your notification preferences. | [`manage_notification_preferences`](https://docs.oqoqo.ai/mcp-server/quota-and-notifications#manage_notification_preferences) |
| [`acp`](https://docs.oqoqo.ai/cli/ask-oqo#oqoqo-acp) | Serve Ask Oqo to an Agent Client Protocol editor. | |
| [`github repos list`](https://docs.oqoqo.ai/cli/ask-oqo#oqoqo-github-repos-list) | List the GitHub accounts and repositories Ask Oqo uses (private beta). | [`list_github_repositories`](https://docs.oqoqo.ai/mcp-server/agents-and-setup#list_github_repositories) |
| [`github repos link`](https://docs.oqoqo.ai/cli/ask-oqo#oqoqo-github-repos-link) | Choose the project for a GitHub repository. | [`manage_github_repository`](https://docs.oqoqo.ai/mcp-server/agents-and-setup#manage_github_repository) |
| [`github repos unlink`](https://docs.oqoqo.ai/cli/ask-oqo#oqoqo-github-repos-unlink) | Remove a GitHub repository's project. | [`manage_github_repository`](https://docs.oqoqo.ai/mcp-server/agents-and-setup#manage_github_repository) |
| [`github accounts connect`](https://docs.oqoqo.ai/cli/ask-oqo#oqoqo-github-accounts-connect) | Connect a GitHub account to your organization. | [`manage_github_repository`](https://docs.oqoqo.ai/mcp-server/agents-and-setup#manage_github_repository) |
| [`github accounts default-project`](https://docs.oqoqo.ai/cli/ask-oqo#oqoqo-github-accounts-default-project) | Set or remove a GitHub account's default project. | [`manage_github_repository`](https://docs.oqoqo.ai/mcp-server/agents-and-setup#manage_github_repository) |
| [`github accounts disconnect`](https://docs.oqoqo.ai/cli/ask-oqo#oqoqo-github-accounts-disconnect) | Disconnect a GitHub account from your organization. | [`disconnect_github_account`](https://docs.oqoqo.ai/mcp-server/agents-and-setup#disconnect_github_account) |
| [`github accounts link-me`](https://docs.oqoqo.ai/cli/ask-oqo#oqoqo-github-accounts-link-me) | Let Ask Oqo know which GitHub account is yours. | [`manage_github_repository`](https://docs.oqoqo.ai/mcp-server/agents-and-setup#manage_github_repository) |

## Related

> [card] [Sign-in and updates](https://docs.oqoqo.ai/cli/sign-in.md)
>
> Sign in, check your identity, and update the CLI.

> [card] [oqoqo experiments](https://docs.oqoqo.ai/cli/experiments.md)
>
> Write a launch plan, launch it, and watch it finish.

> [card] [Use the CLI](https://docs.oqoqo.ai/operate/cli.md)
>
> Define tasks, launch an experiment, and read results from your terminal.

> [card] [Plugin (MCP) reference](https://docs.oqoqo.ai/mcp-server/overview.md)
>
> The same operations from your AI assistant.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.