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 oqoqo 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 carriesexpectedUpdatedAtfromoqoqo 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, useoqoqo uploads create.
oqoqo 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.
oqoqo 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:
oqoqo resources apply as source.repository, source.ref, and source.path. truncated: true means more items exist than one read returns, so narrow --query.
oqoqo 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.
oqoqo resources impact
Check what depends on a resource before you change or delete it.inspect_resource_impact
Arguments
Takes only the global flags.
Examples
oqoqo 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
Pass--operation or --operation-file with JSON that sets action (create or update), kind, and mutationAttemptId (1 to 100 characters). Updates also require targetKey and expectedUpdatedAt from oqoqo catalog list --projection full --output json. Run oqoqo schema resources apply to print every branch and definition key.
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. Oqoqo saves a snapshot at the resolved commit; to pick up later changes, use sync_github with oqoqo resources lifecycle.
Refused writes return resource_not_found, resource_read_only, or resource_revision_conflict (stale expectedUpdatedAt).
oqoqo 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
oqoqo resources apply, with its own mutationAttemptId and expectedUpdatedAt. Oqoqo 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.
oqoqo 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 oqoqo catalog list --projection full.
Examples
Check a GitHub skill for changes:
oqoqo 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.
oqoqo 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 Oqoqo API, and Oqoqo 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 oqoqo uploads complete with it once the bytes reached storage, or run oqoqo uploads create again.
oqoqo uploads get
Read an upload’s status, its last error, and its result.get_upload
Arguments
Takes only the global flags.
Examples
oqoqo 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:
oqoqo uploads get.
Notes
Oqoqo 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.
oqoqo uploads cancel
Cancel an open upload and delete the bytes it stored.cancel_upload
Arguments
Flags
Also takes the global flags.
Examples
oqoqo 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 oqoqo deletions status. When it finishes, Oqoqo pauses each active schedule that can no longer launch and marks it Needs attention.
oqoqo 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 oqoqo resources delete.
Related
oqoqo experiments
Launch an experiment with the tasks and treatments you built.
Tasks and rubrics
What makes a good task and rubric.
Treatments (Toolsets)
Group tools into the sets you compare.
oqoqo tags
Label resources and filter lists by tag.

