Skip to main content
These commands read and change what a project holds: tasks, the files and machines they use, tools, and treatments. Agents appear in the catalog too, so you can find their IDs for a launch plan.

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. Its action (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 mutationAttemptId you 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 carries expectedUpdatedAt from obss catalog list --projection full, or fails with resource_revision_conflict if the resource changed since. A task update also carries the task’s version and versionId.
  • Exact shapes. Send only the fields the shape declares; don’t copy catalog fields such as id, key, version, or versionId into it.
  • Secrets. A definition can name a required header or variable, but never its value. The result returns the setupUrl where a person enters it.
  • Sources. resources apply imports files and skills from public GitHub. For a local folder or ZIP, or tasks from a ZIP, use obss uploads create.

obss catalog list

Search every kind of resource in the project in one call.
Plugin (MCP) tool: inspect_catalog Flags Also takes the global flags. Examples Find the task versions and agent model IDs for a launch plan:
Find the tasks and treatments about checkout, or the resources tagged needs-review:
Result fields 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.
Plugin (MCP) tool: browse_github_source Flags Also takes the global flags. Examples Find a repository, then its refs, then its skill folders:
Notes The command only reads public GitHub repositories and saves nothing. Pass the repository, ref, and path you choose to 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.
Plugin (MCP) tool: inspect_resource Arguments Flags Also takes the global flags. Examples Read a task’s version history, or an MCP server’s definition:
Result fields 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.
Plugin (MCP) tool: inspect_resource_impact Arguments Takes only the global flags. Examples
Result fields

obss resources apply

Create or update one task, file, machine, tool, or treatment from a JSON operation.
Plugin (MCP) tool: 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:
Import a folder of a public repository as a file:
Result fields 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.
Plugin (MCP) tool: 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:
Result fields 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.
Plugin (MCP) tool: manage_resource Flags Pass exactly one of --operation or --operation-file. Also takes the global flags.

Lifecycle operations

Every operation has action, kind, id, mutationAttemptId, and the resource’s current expectedUpdatedAt from obss catalog list --projection full. Examples Check a GitHub skill for changes:
Result fields

obss resources archive

Download a file or skill as a ZIP archive, in base64 pages.
Plugin (MCP) tool: download_resource_archive Arguments Flags Also takes the global flags. Examples
Result fields 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.
Plugin (MCP) tool: create_upload Arguments Flags Also takes the global flags. Examples Upload a folder as a new file:
Replace a file’s content from a script:
Result fields 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.
Plugin (MCP) tool: get_upload Arguments Takes only the global flags. Examples
Result fields

obss uploads complete

Check and apply an upload whose bytes reached storage.
Plugin (MCP) tool: complete_upload
An update replaces a file’s content or adds skill versions, and an official skill change moves the official version. Those need confirmation.
Arguments Flags Also takes the global flags. Examples Finish an upload after its bytes reached storage:
Result fields The same fields as 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.
Plugin (MCP) tool: cancel_upload
Cancelling deletes the archive that the upload stored.
Arguments Flags Also takes the global flags. Examples
Notes Cancelling a cancelled upload returns it again. You can’t cancel a completed upload; change or delete its resources instead.

obss resources delete

Permanently delete experiments and project resources, and everything that depends on them.
Plugin (MCP) tool: delete_resources. With --dry-run: preview_delete_resources.
This deletes the targets and the experiments, runs, Evals, and Insights that depend on them. It also deletes the schedules that launch a deleted experiment, and pauses the schedules whose experiment uses what it deletes. You can’t undo it, so preview it with --dry-run first.
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 a resourceType and exactly one of id or key. Examples Save the targets as delete.json:
Preview the deletion, then delete with the same plan:
Result fields 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.
Plugin (MCP) tool: get_resource_deletion Arguments Takes only the global flags. Examples
Result fields Notes To resume a deletion that didn’t finish, send the same targets with the same --attempt-id to obss resources delete.

Next steps