Resource kinds
Files and machines attach to tasks, and tools attach to treatments. You choose agents when you launch an experiment.
How changes work
You change a resource by sending one JSON operation that states the result you want. Itsaction (create or update) and kind choose the shape, and obss schema resources apply lists every field and limit of each shape.
- Retries. Each operation carries a
mutationAttemptIdyou choose. Resending it returns the first result and changes nothing more. - Concurrent changes. An update names its target by catalog key in
targetKey(a CLI or SDK also accepts its public ID) and carriesexpectedUpdatedAtfromobss catalog list --projection full, or fails withresource_revision_conflictif the resource changed since. A task update also carries the task’sversionandversionId. - Exact shapes. Send only the fields the shape declares; don’t copy catalog fields such as
id,key,version, orversionIdinto it. - Secrets. A definition can name a required header or variable, but never its value. The result returns the
setupUrlwhere a person enters it. - Sources.
resources applyimports files and skills from public GitHub. For a local folder or ZIP, or tasks from a ZIP, useobss uploads create.
obss catalog list
Search every kind of resource in the project in one call.inspect_catalog
Flags
Also takes the global flags.
Examples
Find the task versions and agent model IDs for a launch plan:
needs-review:
Notes
An unknown tag fails with
tag_not_found, and details.tags names it.
obss github browse
Find a public GitHub repository, ref, and path to import as a file or skill.browse_github_source
Flags
Also takes the global flags.
Examples
Find a repository, then its refs, then its skill folders:
obss resources apply as source.repository, source.ref, and source.path. truncated: true means more items exist than one read returns, so narrow --query.
obss resources inspect
Read one resource: its summary, version history, dependencies, or definition.inspect_resource
Arguments
Flags
Also takes the global flags.
Examples
Read a task’s version history, or an MCP server’s definition:
Notes
When a CLI or SDK sets the same variable name as a machine, the tool’s value is used in that tool’s treatments. See When two places set the same variable.
obss resources impact
Check what depends on a resource before you change or delete it.inspect_resource_impact
Arguments
Takes only the global flags.
Examples
obss resources apply
Create or update one task, file, machine, tool, or treatment from a JSON operation.author_resource
Flags
Pass exactly one of
--operation or --operation-file. Also takes the global flags.
Apply operations
A task’s
rubric has schemaVersion: 1 and up to 100 criteria, each with an index (1, 2, 3, in order) and text. Criteria are Yes / no by default, and a run passes when it meets every one. Advanced mode adds a criterion type (boolean “Yes / no”, likert “Quality level”, or numeric “Count or measurement”), negate: true for an unwanted behavior, and a rubric aggregation (all_pass, required_pass, any_pass, weighted_mean, or threshold).
Examples
Create a task with one file and a two-criterion rubric. Save this as task.json:
Because of these two statuses, a script must read
resources[0].id before it uses a new ID.
Notes
A GitHub source.path can be a repository path, a tree or blob path, or a URL in the same repository. source.ref defaults to the default branch, and a missing source.path imports the whole repository. Obss saves a snapshot at the resolved commit; to pick up later changes, use sync_github with obss resources lifecycle.
obss resources bulk-apply
Apply up to 20 resource operations in order, each one retryable on its own.bulk_author_resources
Flags
Pass exactly one of
--batch or --batch-file. Also takes the global flags.
Examples
Save 1 to 20 operations as { "operations": [ ... ] } in batch.json:
Notes
Each operation has the same shape as in
obss resources apply, with its own mutationAttemptId and expectedUpdatedAt. Obss applies them one at a time, in order. When one fails, correct it and send the whole batch again; the finished operations return their first results.
obss resources lifecycle
Set official versions and the default machine, sync a file or skill from GitHub, or move a treatment’s tools to their latest versions.manage_resource
Flags
Pass exactly one of
--operation or --operation-file. Also takes the global flags.
Lifecycle operations
Every operation hasaction, kind, id, mutationAttemptId, and the resource’s current expectedUpdatedAt from obss catalog list --projection full.
Examples
Check a GitHub skill for changes:
obss resources archive
Download a file or skill as a ZIP archive, in base64 pages.download_resource_archive
Arguments
Flags
Also takes the global flags.
Examples
Notes
Use
--output json. After the last page, join the pages and check the SHA-256.
obss uploads create
Upload a local folder or ZIP archive as a file, as skills, or as a task import, and apply it.create_upload
Arguments
Flags
Also takes the global flags.
Examples
Upload a folder as a new file:
Notes
The CLI zips a folder (paths relative to it), skips
.DS_Store, __MACOSX, and empty folders, and refuses symbolic links. ZIP is the only archive format; skills also accept .skill. The bytes go straight to storage, not through the Obss API, and Obss applies each upload exactly once.
Creating resources needs no confirmation. An update, or a change to an official skill version, changes existing content, so the CLI asks you to confirm in a terminal. With
--output json, or without a terminal, pass --yes.
If the transfer fails, the error names the upl_ upload ID. Run obss uploads complete with it once the bytes reached storage, or run obss uploads create again.
obss uploads get
Read an upload’s status, its last error, and its result.get_upload
Arguments
Takes only the global flags.
Examples
obss uploads complete
Check and apply an upload whose bytes reached storage.complete_upload
Arguments
Flags
Also takes the global flags.
Examples
Finish an upload after its bytes reached storage:
obss uploads get.
Notes
Obss checks the archive’s size and SHA-256, validates the ZIP, and applies the operation. Completing a completed upload again returns its first result. Archive problems keep the upload open and list each issue in lastError.
obss uploads cancel
Cancel an open upload and delete the bytes it stored.cancel_upload
Arguments
Flags
Also takes the global flags.
Examples
obss resources delete
Permanently delete experiments and project resources, and everything that depends on them.delete_resources. With --dry-run: preview_delete_resources.
Flags
Pass exactly one of
--targets or --targets-file. Also takes the global flags.
Targets
The targets are a JSON array of 1 to 100 objects. Each has aresourceType and exactly one of id or key.
Examples
Save the targets as
delete.json:
Notes
The text output prints the same lines as the dashboard, such as “Pauses the schedule Nightly checkout: it launches an experiment that uses what this deletes”.
A blocker makes the command fail with
resource_deletion_blocked without asking you to confirm. In a terminal, the deletion is refused if the plan changes before the CLI sends it. --yes sends it at once, so add --plan-hash to refuse a changed plan with resource_deletion_plan_changed.
The deletion runs after the command returns, so read its status with obss deletions status. When it finishes, Obss pauses each active schedule that can no longer launch and marks it Needs attention.
obss deletions status
Read the status of a resource deletion and why it failed.get_resource_deletion
Arguments
Takes only the global flags.
Examples
Notes
To resume a deletion that didn’t finish, send the same targets with the same
--attempt-id to obss resources delete.
