# CLI reference - Obss

CLI
CLI reference
Install and update the obss CLI, sign in, pick a project, and learn the flags, output, exit codes, and rules that every command shares.
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):
curl
-fsSL
https://obss.app/install
|
sh
The script installs
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, run
obss upgrade
. It works without a sign-in.
obss
upgrade
obss
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
obss version
and read
autoUpdate
.
Condition
Checks for a release
Installs in the background
Prints update notices
OBSS_DISABLE_AUTOUPDATE
is set
Yes
No
Yes
OBSS_NO_UPDATE_NOTIFIER
is set
No
No
No
CI
is set
No
No
No
OBSS_API_KEY
is set
No
No
No
The CLI runs from source, not from an installed binary
No
No
No
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:
Updated obss 2026.11.10.1 -> 2026.11.12.1 in the background.
A new obss release is available: 2026.11.10.1 -> 2026.11.12.1. Run `obss upgrade` to update.
The first line appears after a background install. The second appears when
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 code
4
, and prints:
obss: This obss release is older than the server supports: run `obss upgrade`, then retry.
With
--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, run
obss 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.
obss
login
obss
whoami
The CLI keeps your sign-in and saved project in
~/.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_KEY
where the CLI runs.
export
OBSS_API_KEY
=
"
$OBSS_PERSONAL_KEY
"
obss
whoami
While
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 whoami
reports
credential
as
api_key
.
obss login
refuses to sign in, and
obss logout
removes only the saved sign-in.
The CLI doesn’t check for or install updates; run
obss 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:
The
--project-id
flag 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
list
obss
projects
use
prj_4d7a20c5
obss
experiments
list
--project-id
prj_9b13e6f2
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 in
obss experiments list --output json
.
Flag
Type
Default
Description
--output
,
-o
text
,
json
text
Output format.
json
prints one JSON envelope on stdout. See
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
OBSS_DEBUG=1
. Logs never contain tokens or keys.
--help
,
-h
boolean
false
Show help for the command, like
obss help <command>
.
--expected-organization-id
string
Run only in this organization. Read the ID from
obss 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.
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:
{
"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
obss schema <command>
.
A failure looks like this:
{
"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: Obss’s own code when the server gave one, such as
schedule_changed
, or else a CLI code from
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
obss: <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 Obss refused your API key.
not_logged_in
,
auth_expired
,
auth_denied
4
Obss 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 Obss’s own code
5
Network error: the CLI could not reach Obss.
network_error
6
The command succeeded, and the result matched a flag that you set to fail on it:
experiments watch --fail-on
or
experiments preflight --require-ready
. 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
obss <group> --help
.
Environment variables
Variable
Effect
OBSS_API_KEY
A personal
API key
that every command sends instead of your saved sign-in. Also turns off
background updates
.
OBSS_DISABLE_AUTOUPDATE
Turns off background installs, but not checks and notices.
OBSS_NO_UPDATE_NOTIFIER
Turns off update checks, background installs, and notices.
CI
Same as
OBSS_NO_UPDATE_NOTIFIER
. Most CI services set it.
OBSS_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/obss
instead of
~/.config/obss
.
OBSS_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 something. In a terminal, the CLI shows what will change and asks you to confirm with
y
. With
--output json
, or without a terminal, pass
--yes
instead; without it, the command changes nothing and exits with code
2
.
obss
schedules
delete
sch_c0a9f311
--lock-version
3
--yes
--output
json
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 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)
obss schedules get
schedule_changed
--lock-version
(public links)
obss experiments publications get
publication_changed
--expected-updated-at
(projects)
obss projects inspect
project_update_stale
--expected-updated-at
(tags)
obss tags list
tag_changed
expectedUpdatedAt
in an operation,
--expected-updated-at
on
uploads create
obss catalog list --projection full
resource_revision_conflict
projectConfigurationRevision
,
organizationConfigurationRevision
in a launch plan
obss catalog list --kind agent --projection full
, or
obss experiments preflight
configuration_changed
--plan-hash
obss 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.
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 as
setupUrl
: 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 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
.
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.
Command index
obss
command
What it does
Plugin (MCP) tool
login
Sign in with your browser.
whoami
Show who you are signed in as, and how.
get_identity
logout
Remove your saved sign-in.
version
Show the version, channel, and update setting.
upgrade
Install the latest release now.
schema
Print each command’s JSON Schema.
projects list
List projects and mark the current one.
get_project_context
projects current
Show the current project and its source.
get_project_context
projects use
Save a project for later commands.
get_project_context
projects inspect
Show one project.
get_project_context
projects create
Create a project.
manage_project
projects update
Rename a project.
manage_project
projects delete
Permanently delete a project.
preview_delete_project
,
delete_project
catalog list
Search every kind of project resource.
inspect_catalog
github browse
Find a public GitHub source to import.
browse_github_source
resources inspect
Read a resource’s detail, versions, or definition.
inspect_resource
resources impact
Check what depends on a resource.
inspect_resource_impact
resources apply
Create or update one resource from JSON.
author_resource
resources bulk-apply
Apply up to 20 resource operations.
bulk_author_resources
resources lifecycle
Set official versions and defaults, or sync from GitHub.
manage_resource
resources archive
Download a file or skill as a ZIP.
download_resource_archive
uploads create
Upload a folder or ZIP as a file, skills, or tasks.
create_upload
uploads get
Read an upload’s status and result.
get_upload
uploads complete
Check and apply an uploaded archive.
complete_upload
uploads cancel
Cancel an open upload.
cancel_upload
resources delete
Permanently delete experiments and resources.
preview_delete_resources
,
delete_resources
deletions status
Read a deletion’s status.
get_resource_deletion
experiments preflight
Check a launch plan without launching.
preflight_experiment
experiments launch
Launch an experiment from a plan.
launch_experiment
experiments status
Read an experiment’s progress once.
get_experiment_status
,
get_launch_status
experiments watch
Wait until an experiment ends.
get_experiment_status
,
get_launch_status
experiments list
List and filter experiments.
list_experiments
experiments get
Read an experiment’s progress, lineage, and runs used.
get_experiment
experiments brief
Read an experiment’s Brief: its differences and the frictions seen with them.
get_experiment_brief
experiments clone-plan
Get a launch plan from an experiment.
get_experiment_plan
experiments rerun
Launch a finished experiment again.
rerun_experiment
experiments cancel
Cancel an experiment or one run.
cancel_experiment
experiments publish
Publish a completed experiment at a public link.
publish_experiment
experiments publications list
List your organization’s public links.
list_experiment_publications
experiments publications get
Read one public link.
get_experiment_publication
experiments publications update
Publish the latest results to a public link.
update_experiment_publication
experiments publications unpublish
Stop sharing a public link.
unpublish_experiment
gallery get
Read results from a public link.
get_public_experiment
schedules preview
Preview a schedule’s launches and runs.
preview_schedule
schedules create
Schedule a finished experiment.
manage_schedule
schedules list
List the project’s schedules.
list_schedules
schedules get
Read one schedule.
get_schedule
schedules update
Change a schedule’s name, cadence, or experiment.
manage_schedule
schedules pause
Pause a schedule.
manage_schedule
schedules resume
Resume a paused schedule.
manage_schedule
schedules launch
Launch a schedule’s experiment now.
rerun_experiment
schedules delete
Delete a schedule.
delete_schedule
runs list
List run results.
list_runs
runs profile
Show a run’s treatment use, tool calls, and time.
get_run_profile
runs trajectory
Page a run’s steps.
get_run_trajectory
runs transcript
Read a run’s original transcript.
get_run_transcript
runs output
Read a run’s output files and diffs.
get_run_output
results analyze
Summarize, compare, and search results.
analyze_results
frictions list
Rank the project’s frictions.
list_frictions
frictions get
Read one friction.
get_friction
evals preview
Check which runs can get Evals.
preview_evals
evals trigger
Run Evals on an experiment’s runs.
trigger_evals
evals list
List an experiment’s Evals attempts.
list_evals
evals get
Read the results of an Evals attempt.
get_evals_results
evals compare
Compare an experiment’s treatments and agents.
get_evals_comparisons
insights preview
Check whether Insights can run.
preview_insights
insights trigger
Run Insights on an experiment’s runs.
trigger_insights
insights list
List an experiment’s Insights attempts.
list_insights
insights get
Read the results of an Insights attempt.
get_insights_results
tags list
List the project’s tags.
list_tags
tags add
Add tags to records.
update_tags
tags remove
Remove tags from records.
update_tags
tags rename
Rename a tag.
rename_tag
tags delete
Delete a tag from every record.
delete_tag
data describe
List the datasets and fields you can query.
inspect_data_model
data query
Query, group, and count Obss data.
query_data
project ai inspect
Read agents, providers, models, and Obss AI features.
inspect_project_ai
project ai apply
Change agents, models, custom agents, and Obss AI features.
manage_project_ai
project ai delete
Remove a custom agent or a provider connection.
delete_project_ai
project ai test-agent
Test a custom agent with one run.
test_custom_agent
setup links
List web links for values you enter in the dashboard.
get_setup_links
mcp accounts inspect
Check your connection to an MCP server.
inspect_mcp_account
mcp accounts detect-auth
Detect how an MCP server signs in.
detect_mcp_auth_mode
mcp tools list
List an MCP server’s tools.
list_mcp_server_tools
mcp tools refresh
Check an MCP server’s tools again.
refresh_mcp_server_tools
quota inspect
Show the run balance.
inspect_quota
quota ledger
List run balance history.
list_quota_ledger
notifications list
List your notifications.
list_notifications
notifications acknowledge
Mark notifications as read.
acknowledge_notifications
notifications preferences
Show your notification preferences.
inspect_notification_preferences
notifications preferences update
Change your notification preferences.
manage_notification_preferences
acp
Serve Ask Obss to an Agent Client Protocol editor.
ask disconnect
Disconnect Ask Obss from your account.
disconnect_ask_oqo
Next steps
Sign-in and updates
Sign in, check your identity, and update the CLI.
obss 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.
Sign-in and updates
Powered by
This documentation is built and hosted on Mintlify, a developer documentation platform