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.
Every command except login, logout, version, upgrade, schema, and acp has a matching tool in the Plugin (MCP) reference, with the same inputs and result fields. New to the CLI? Start with Use the CLI.
Install
Run the install script on macOS or Linux (arm64 or x64):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, runoqoqo upgrade. It works without a sign-in.
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, runoqoqo version and read autoUpdate.
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: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 code4, and prints:
--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 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 shows.
Sign in
To sign in, runoqoqo 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.
~/.config/oqoqo, or in $XDG_CONFIG_HOME/oqoqo when that variable is set. 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.- In the dashboard, open Profile → API keys and create a key.
- Store the key as a secret, and set it as
OQOQO_API_KEYwhere the CLI runs.
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 whoamireportscredentialasapi_key. oqoqo loginrefuses to sign in, andoqoqo logoutremoves only the saved sign-in.- The CLI doesn’t check for or install updates; run
oqoqo upgradeyourself. - A CI job has no saved project, so pass
--project-idon every command.
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:- The
--project-idflag on the command. It applies to that one call and is never saved. - The project you saved with
oqoqo projects use. - A project that Oqoqo chooses for you when you saved none.
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 inoqoqo experiments list --output json.
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:
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:
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
When you mistype a command, the message suggests the closest command in that group and tells you to run
oqoqo <group> --help.
Environment variables
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 entery. In non-interactive runs or with --output json, pass --yes; otherwise the CLI makes no changes and exits with code 2.
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 aslaunch_attempt_conflict.
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.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.
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 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 assetupUrl: open it where you’re signed in, enter the value, and continue in the CLI. 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.
IDs
Commands take and return stable public IDs, and each ID starts with a prefix that names its kind, such asprj_, 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.
Read command schemas
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
Related
Sign-in and updates
Sign in, check your identity, and update the CLI.
oqoqo experiments
Write a launch plan, launch it, and watch it finish.
Use the CLI
Define tasks, launch an experiment, and read results from your terminal.
Plugin (MCP) reference
The same operations from your AI assistant.

