obss is the command-line client for Obss. 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):obss in ~/.local/bin when that folder is on your PATH, and in ~/.obss/bin otherwise, so you don’t need sudo. To choose another folder, set OBSS_INSTALL_DIR before you run it. The dashboard shows the same command under Automate → Obss CLI.
Keep the CLI current
To install the latest release right away, runobss 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, runobss version and read autoUpdate.
OBSS_DISABLE_AUTOUPDATE, OBSS_NO_UPDATE_NOTIFIER, and CI count as set unless their value is empty, 0, false, or no. obss 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:OBSS_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 Obss refuses an old release
When Obss no longer accepts your installed release, any command that contacts Obss changes nothing, exits with code4, and prints:
--output json, error.code is client_update_required. Run obss upgrade, then run the command again. obss upgrade, obss version, and obss schema don’t contact the Obss 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 Obss as a custom agent shows.
Sign in
To sign in, runobss login. It opens Obss 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/obss, or in $XDG_CONFIG_HOME/obss when that variable is set. obss 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
OBSS_API_KEYwhere the CLI runs.
OBSS_API_KEY is set:
- Every command sends the key instead of your saved sign-in, acting as you in the key’s organization.
obss whoamireportscredentialasapi_key. obss loginrefuses to sign in, andobss logoutremoves only the saved sign-in.- The CLI doesn’t check for or install updates; run
obss 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
obss projects use. - A project that Obss chooses for you when you saved none.
obss 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 Obss chooses again.
Global flags
Every command takes these flags. Put flags after the command words, as inobss experiments list --output json.
obss --help lists every command, and obss --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 obss schema <command>.
A failure looks like this:
In text mode, an error prints on stderr as
obss: <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
obss <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 something. In a terminal, the CLI shows what will change and asks you to confirm withy. With --output json, or without a terminal, pass --yes instead; without it, the command changes nothing and exits with code 2.
obss projects delete and obss resources delete also take --dry-run, which shows what the deletion would stop and remove, and what blocks it, without changing anything. When something blocks a deletion, the CLI doesn’t ask you to confirm. It fails with the blockers, such as project_deletion_blocked or resource_deletion_blocked.
Commands that spend runs or publish results, such as obss experiments launch, don’t ask for confirmation unless they’re also destructive. Ask Obss asks you to approve each of these calls, and each command page marks them.
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.obss experiments status --wait-ms waits in the server up to 25,000 milliseconds for a change, and obss 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. obss 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
obss schema lists every command, and obss 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.
