> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oqoqo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# oqoqo catalog, resources, and uploads

> Search a project's tasks, files, machines, tools, treatments, and agents, and create, update, upload, and delete them from the CLI.

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

| Kind | ID prefix | What it is | Guide |
| - | - | - | - |
| `task` | `tsk_`, version `tskver_` | The work: instructions, a rubric, files, and a machine. | [Tasks and rubrics](https://docs.oqoqo.ai/experiments/tasks.md) |
| `file` | `fld_` | A folder of starting files that a task mounts for the agent. | [Machines and files](https://docs.oqoqo.ai/experiments/machines-and-files.md) |
| `machine` | `env_` | The computer a task runs on. | [Machines and files](https://docs.oqoqo.ai/experiments/machines-and-files.md) |
| `skill`, `mcp`, `cli`, `sdk` | `skl_`, `mcp_`, `cli_`, `sdk_`, versions `sklver_`, `mcpver_`, `cliver_`, `sdkver_` | Tools: skills, MCP servers, CLIs, and SDKs. | [Tools](https://docs.oqoqo.ai/experiments/tools.md) |
| `treatment` | `trt_` | A treatment (toolset): the tools an agent gets. | [Treatments (Toolsets)](https://docs.oqoqo.ai/experiments/treatments.md) |
| `agent` | `agm_` | An agent with one model. Read-only here. | [Agents](https://docs.oqoqo.ai/setup/agents.md) |

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 `oqoqo 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 `oqoqo 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](https://docs.oqoqo.ai/cli/overview.md#secrets-stay-in-the-dashboard). 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 [`oqoqo uploads create`](#oqoqo-uploads-create).

## oqoqo catalog list

Search every kind of resource in the project in one call.

```bash theme={null}
oqoqo catalog list [flags]
```

**Plugin (MCP) tool:** [`inspect_catalog`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#inspect_catalog)

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--kind` | string | | Comma-separated kinds: `task`, `file`, `machine`, `skill`, `mcp`, `cli`, `sdk`, `treatment`, `agent`. |
| `--query` | string | | Resources whose name, key, or ID matches. |
| `--projection` | `compact`, `full` | `compact` | `full` adds `description`, `contentHash`, `isOfficial`, `isReadOnly`, `createdAt`, `updatedAt`, and `facts` to each item. |
| `--tag` | string | | Resources with any of these comma-separated tags, by name or `tag_` ID. |
| `--untagged` | boolean | `false` | Resources with no tags. With `--tag`, resources with those tags or with none. |
| `--limit` | integer | `100` | Results per page, up to 500 (default 100). |
| `--cursor` | string | | The `page.nextCursor` from the previous page. |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Find the task versions and agent model IDs for a launch plan:

```bash theme={null}
oqoqo catalog list --kind task,agent --projection full --output json
```

Find the tasks and treatments about checkout, or the resources tagged `needs-review`:

```bash theme={null}
oqoqo catalog list --kind task,treatment --query checkout
oqoqo catalog list --tag needs-review
```

**Result fields**

| Field | Description |
| - | - |
| `kind`, `id`, `key`, `name` | Each item's kind, public ID, key, and name. An agent's `id` is its `agm_` agent model ID. |
| `versionId`, `version` | The current version. A launch plan selects a task by its `tskver_` `versionId`. |
| `status`, `tags`, `dashboardUrl` | The item's status, tags, and dashboard page. |
| `agentKind`, `customStatus` | Custom agents only. |
| `facts.projectConfigurationRevision`, `facts.organizationConfigurationRevision` | Agents, with `--projection full`: the configuration versions a launch plan needs. |
| `facts.turnsOffMcpTools` | Agents, with `--projection full`: whether the agent can run a treatment that turns MCP tools off. |
| `facts.toolCount` | MCP servers, with `--projection full`: how many tools the latest version listed at its last check, or `null` until a check lists them. |
| `total`, `kindCounts` | The matching items, in total and by kind. |
| `page.hasMore`, `page.nextCursor` | Whether another page exists, and the cursor for it. |

**Notes**

An unknown [tag](https://docs.oqoqo.ai/experiments/tags.md) 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.

```bash theme={null}
oqoqo github browse --view <view> [flags]
```

**Plugin (MCP) tool:** [`browse_github_source`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#browse_github_source)

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--view` | `repositories`, `refs`, `paths` | | Required. What to list. |
| `--query` | string | | Required for `repositories`: a name, `owner/name`, `owner/`, or a GitHub URL. For `refs`, every branch and tag whose name starts with it. For `paths`, only paths that contain it. |
| `--repository` | string | | Required for `refs` and `paths`. A public `github.com` `owner/repository`, or a repository, tree, blob, or commit URL. |
| `--ref` | string | | `paths` only: a branch, tag, or commit. Without it, the ref in the URL or the default branch. |
| `--kind` | `skill`, `file` | | `paths` only. `file` lists folders and files. `skill` lists skill folders and how many skills each one imports. |
| `--limit` | integer | By view | Results to return, up to 30 for `repositories` (default 10), 200 for `refs` (default 100), and 1,000 for `paths` (default 100). |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Find a repository, then its refs, then its skill folders:

```bash theme={null}
oqoqo github browse --view repositories --query anthropics/
oqoqo github browse --view refs --repository anthropics/skills
oqoqo github browse --view paths --repository anthropics/skills --kind skill
```

**Notes**

The command only reads public GitHub repositories and saves nothing. Pass the repository, ref, and path you choose to [`oqoqo resources apply`](#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.

```bash theme={null}
oqoqo resources inspect <kind> <id> [flags]
```

**Plugin (MCP) tool:** [`inspect_resource`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#inspect_resource)

**Arguments**

| Argument | Description |
| - | - |
| `<kind>` | Required. `task`, `file`, `machine`, `skill`, `mcp`, `cli`, `sdk`, or `treatment`. |
| `<id>` | Required. The resource's public ID, such as `tsk_3a91c7e2`, or its key. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--view` | `summary`, `versions`, `dependencies`, `definition` | `summary` | What to read. |
| `--version` | integer | | Read this version. Without it, the current version. |
| `--before-version` | integer | | `versions` view: continue with versions older than this one. |
| `--version-limit` | integer | `50` | `versions` view: maximum versions, capped at 100. |
| `--limit` | integer | `100` | `dependencies` view: results per page, up to 500 (default 100). |
| `--cursor` | string | | `dependencies` view: the `page.nextCursor` from the previous page. |
| `--offset` | integer | `0` | `definition` view: the byte to start from. |
| `--limit-bytes` | integer | `12288` | `definition` view: bytes to return. One page holds at most 12,288 bytes. |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Read a task's version history, or an MCP server's definition:

```bash theme={null}
oqoqo resources inspect task tsk_3a91c7e2 --view versions
oqoqo resources inspect mcp mcp_8c42d1f7 --view definition --output json
```

**Result fields**

| Field | Description |
| - | - |
| `resource`, `selectedVersion`, `counts` | Returned by every view. |
| `nextOffset`, `eof` | `definition` view: continue with `--offset` until `eof` is true. |
| `hasMore`, `nextBeforeVersion` | `versions` view: while `hasMore` is true, pass `nextBeforeVersion` as `--before-version`. |
| `definition.sourceAction` | A file's or skill's `definition` view, when it was imported from GitHub: the link (`href`) and the `repository` as `owner/name`, `ref`, `path`, and `commitSha` of the saved snapshot. `ref` is null when the import named a commit, `path` is null for a whole repository, and `sourceAction` is null for an upload. |
| `variableOverrides` | A machine's `definition` view: each machine variable whose name a CLI or SDK in the project also sets, with those `tools` and a `note`. |

**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](https://docs.oqoqo.ai/experiments/machines-and-files.md#when-two-places-set-the-same-variable).

## oqoqo resources impact

Check what depends on a resource before you change or delete it.

```bash theme={null}
oqoqo resources impact <kind> <id> [flags]
```

**Plugin (MCP) tool:** [`inspect_resource_impact`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#inspect_resource_impact)

**Arguments**

| Argument | Description |
| - | - |
| `<kind>` | Required. `task`, `file`, `machine`, `skill`, `mcp`, `cli`, `sdk`, or `treatment`. |
| `<id>` | Required. The resource's public ID or key. |

Takes only the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

```bash theme={null}
oqoqo resources impact skill skl_4be07a93
```

**Result fields**

| Field | Description |
| - | - |
| `dependencies` | The tasks and treatments that use the resource. |
| `outdatedTreatmentIds` | The treatments that use an older version. |
| `canMutate` | Whether you can change or delete the resource. |
| `reason` | Why `canMutate` is false, for example because Oqoqo manages the resource. |

## oqoqo resources apply

Create or update one task, file, machine, tool, or treatment from a JSON operation.

```bash theme={null}
oqoqo resources apply --operation-file <path> [flags]
```

**Plugin (MCP) tool:** [`author_resource`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#author_resource)

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--operation` | string | | The operation as inline JSON. |
| `--operation-file` | file path | | A file that holds the operation JSON. |

Pass exactly one of `--operation` or `--operation-file`. Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#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.

| `kind` | Create fields | Update rules and notes |
| - | - | - |
| `task` | `name`, `instructionsMarkdown`, `environmentId` (the `env_` machine, from `oqoqo catalog list --kind machine`), `rubric`, `assetAttachments` | Updates also require `versionId` and `version` of the version you read. Each attached file has a `projectAssetId` (`fld_`) and a `mountPath`. Refer to each `mountPath` in the instructions. |
| `machine` | `name`, `description`, `definition` | See [Machines and files](https://docs.oqoqo.ai/experiments/machines-and-files.md) and `oqoqo schema resources apply` for `definition` keys. |
| `mcp`, `cli`, `sdk` | `name`, `description`, `definition` | A CLI's `commands` lists every executable name its install puts on `PATH`. A `postInstall` command, and an MCP server's `url`, `command`, or `args`, name a declared value as `${NAME}`. See [Tools](https://docs.oqoqo.ai/experiments/tools.md#keys-in-a-url-or-an-argument). |
| `treatment` | `name`, `description`, `skillVersionIds`, `mcpServerVersionIds`, `cliVersionIds`, `sdkVersionIds`, `disabledMcpTools` | On an update, send all four `*VersionIds` arrays (using `[]` for empty lists). `disabledMcpTools` [turns off some tools](https://docs.oqoqo.ai/experiments/treatments.md#turn-off-mcp-tools) of an MCP server. |
| `file`, `skill` | `source` | Send `source` only (no `name` or `description`): `kind` is `github`, with `repository` and optional `ref` and `path`. |

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](https://docs.oqoqo.ai/experiments/tasks.md) 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`:

```json theme={null}
{
  "action": "create",
  "kind": "task",
  "mutationAttemptId": "create-partial-refund-01",
  "name": "Issue a partial refund",
  "instructionsMarkdown": "Refund $20 of order 1042 with the payments API. Customer records are in `fixtures/`.",
  "environmentId": "env_2f8a61c4",
  "assetAttachments": [
    { "projectAssetId": "fld_6d0b93e1", "mountPath": "fixtures" }
  ],
  "rubric": {
    "schemaVersion": 1,
    "criteria": [
      { "index": 1, "text": "Creates a refund of exactly $20 for order 1042." },
      { "index": 2, "text": "Leaves the rest of the order amount charged." }
    ]
  }
}
```

```bash theme={null}
oqoqo resources apply --operation-file ./task.json --output json
```

Import a folder of a public repository as a file:

```bash theme={null}
oqoqo resources apply --operation '{"action":"create","kind":"file","mutationAttemptId":"import-fixtures-01","source":{"kind":"github","repository":"acme/checkout-fixtures","ref":"v2.1.0","path":"customers"}}'
```

**Result fields**

| Field | Description |
| - | - |
| `action`, `message` | The action you sent, and what happened in plain words. |
| `status` | One of the values in the next table. |
| `resources[].kind`, `id`, `key`, `name` | Each resource the operation touched. A treatment's `id` is its `trt_` ID. |
| `resources[].versionId`, `version`, `contentHash` | The saved version. A task's `versionId` is the `tskver_` ID that a launch plan needs; a treatment's is `null`. |
| `resources[].dashboardUrl`, `setupUrl` | The resource's dashboard page, and where a person enters a missing value. |

| `status` | Meaning |
| - | - |
| `created`, `updated`, `renamed`, `unchanged` | Oqoqo created, updated, or renamed the resource, or found nothing to change. |
| `matched_existing` | Treatments only: a treatment with the same tools already exists, so Oqoqo saves nothing and returns it, because a treatment is its toolset. `message` names it. |
| `name_conflict` | Treatments only: another treatment has that name, so Oqoqo saves nothing and returns that treatment. `message` says why. |

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`](#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.

```bash theme={null}
oqoqo resources bulk-apply --batch-file <path> [flags]
```

**Plugin (MCP) tool:** [`bulk_author_resources`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#bulk_author_resources)

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--batch` | string | | The batch as inline JSON. |
| `--batch-file` | file path | | A file that holds the batch JSON. |

Pass exactly one of `--batch` or `--batch-file`. Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Save 1 to 20 operations as `{ "operations": [ ... ] }` in `batch.json`:

```bash theme={null}
oqoqo resources bulk-apply --batch-file ./batch.json --output json
```

**Result fields**

| Field | Description |
| - | - |
| `results` | The finished operations' results, in order, each as [`oqoqo resources apply`](#oqoqo-resources-apply) returns it. |
| `failure` | When an operation fails: `failedIndex`, `failedMutationAttemptId`, the error, and `notStartedCount`. |

**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.

```bash theme={null}
oqoqo resources lifecycle --operation-file <path> [flags]
```

**Plugin (MCP) tool:** [`manage_resource`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#manage_resource)

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--operation` | string | | The lifecycle operation as inline JSON. |
| `--operation-file` | file path | | A file that holds the operation JSON. |

Pass exactly one of `--operation` or `--operation-file`. Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

### Lifecycle operations

Every operation has `action`, `kind`, `id`, `mutationAttemptId`, and the resource's current `expectedUpdatedAt` from `oqoqo catalog list --projection full`.

| `action` | `kind` | What it does |
| - | - | - |
| `set_official`, `clear_official` | `skill`, `mcp`, `cli`, `sdk` | Mark a version (`versionId`) as official, the one you declare as part of your product's interface, or clear it. |
| `set_default`, `clear_default` | `machine` | Make the machine the project's default, or clear it. |
| `sync_github` | `file`, `skill` | Check the saved GitHub source, and save a new snapshot only when the selected content changed. Past runs keep their snapshot. |
| `update_members_to_current` | `treatment` | Move each tool in the treatment to its latest version. |

**Examples**

Check a GitHub skill for changes:

```bash theme={null}
oqoqo resources lifecycle --operation '{"action":"sync_github","kind":"skill","id":"skl_4be07a93","mutationAttemptId":"sync-skill-2026-11-12","expectedUpdatedAt":"2026-11-10T16:42:05Z"}'
```

**Result fields**

| Field | Description |
| - | - |
| `action`, `status`, `resourceId` | The action, its result, and the resource. |
| `updatedAt` | The resource's new `updatedAt`, for your next change. |
| `officialVersionId`, `defaultMachineId`, `changedMembers`, `commitSha` | The field the action changed. |

## oqoqo resources archive

Download a file or skill as a ZIP archive, in base64 pages.

```bash theme={null}
oqoqo resources archive <kind> <id> [flags]
```

**Plugin (MCP) tool:** [`download_resource_archive`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#download_resource_archive)

**Arguments**

| Argument | Description |
| - | - |
| `<kind>` | Required. `file` or `skill`. |
| `<id>` | Required. The `fld_` or `skl_` ID. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--version` | integer | | A skill version. Without it, the current version. |
| `--offset` | integer | `0` | The byte of the archive to start from. |
| `--limit-bytes` | integer | `12288` | Bytes to return. One page holds at most 12,288 bytes. |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

```bash theme={null}
oqoqo resources archive skill skl_4be07a93 --output json
```

**Result fields**

| Field | Description |
| - | - |
| `archiveBase64` | This page's bytes, in base64. |
| `fileName`, `byteSize`, `sha256` | The whole archive's name, size, and SHA-256. |
| `nextOffset`, `eof` | Continue with `--offset` set to `nextOffset` until `eof` is true. |

**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.

```bash theme={null}
oqoqo uploads create <path> --kind <kind> [flags]
```

**Plugin (MCP) tool:** [`create_upload`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#create_upload)

**Arguments**

| Argument | Description |
| - | - |
| `<path>` | Required. The local folder or ZIP archive to upload. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--kind` | `file`, `skill`, `task` | | Required. `file` creates a file or replaces a file's content. `skill` creates or versions the skills in the archive. `task` imports tasks from an `oqoqo-task-import` ZIP. |
| `--name` | string | | `file` only. The display name. Defaults to the archive name. Required to update a file. |
| `--description` | string | | `file` only. The description. |
| `--target` | string | | Update this file or skill instead of creating one, by key or public ID. |
| `--expected-updated-at` | string | | Required with `--target`. The target's current `updatedAt` from `oqoqo catalog list --projection full`. |
| `--mark-official` | boolean | | `skill` only. Make each imported skill version official. |
| `--yes` | boolean | `false` | Skip interactive confirmation for an update or official skill change. Required with `--output json` or outside a terminal. |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Upload a folder as a new file:

```bash theme={null}
oqoqo uploads create ./fixtures/customers --kind file --name "Customer fixtures"
```

Replace a file's content from a script:

```bash theme={null}
oqoqo uploads create ./fixtures/customers --kind file --name "Customer fixtures" --target fld_6d0b93e1 --expected-updated-at 2026-11-10T16:42:05Z --yes --output json
```

**Result fields**

| Field | Description |
| - | - |
| `upload` | The upload, with the fields of [`oqoqo uploads get`](#oqoqo-uploads-get). |
| `transfer` | `null`, because the CLI already used it. |

**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.

| Kind | Archive size | Expanded size | Files and folders |
| - | - | - | - |
| `file`, `task` | 512 MiB | 512 MiB | 65,535 |
| `skill` | 256 MiB | 256 MiB | 65,535 |

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.

```bash theme={null}
oqoqo uploads get <upload-id> [flags]
```

**Plugin (MCP) tool:** [`get_upload`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#get_upload)

**Arguments**

| Argument | Description |
| - | - |
| `<upload-id>` | Required. The `upl_` upload ID. |

Takes only the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

```bash theme={null}
oqoqo uploads get upl_9e04a6d2 --output json
```

**Result fields**

| Field | Description |
| - | - |
| `status` | `awaiting_upload`, `completed`, `failed`, `cancelled`, or `expired`. |
| `result` | On a completed upload, the files, skills, or tasks it created or updated. |
| `lastError` | On an open upload, each archive issue. |
| `uploadUrl` | On an open upload, the dashboard page where a person can choose a fixed archive. That page completes the upload. |

## oqoqo uploads complete

Check and apply an upload whose bytes reached storage.

```bash theme={null}
oqoqo uploads complete <upload-id> [flags]
```

**Plugin (MCP) tool:** [`complete_upload`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#complete_upload)

> [!WARNING]
>
> An update replaces a file's content or adds skill versions, and an official skill change moves the official version. Those need confirmation.

**Arguments**

| Argument | Description |
| - | - |
| `<upload-id>` | Required. The `upl_` upload ID. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--yes` | boolean | `false` | Skip interactive confirmation. Required with `--output json` or outside a terminal. |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Finish an upload after its bytes reached storage:

```bash theme={null}
oqoqo uploads complete upl_9e04a6d2 --yes --output json
```

**Result fields**

The same fields as [`oqoqo uploads get`](#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.

```bash theme={null}
oqoqo uploads cancel <upload-id> [flags]
```

**Plugin (MCP) tool:** [`cancel_upload`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#cancel_upload)

> [!WARNING]
>
> Cancelling deletes the archive that the upload stored.

**Arguments**

| Argument | Description |
| - | - |
| `<upload-id>` | Required. The `upl_` upload ID. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--yes` | boolean | `false` | Skip interactive confirmation. Required with `--output json` or outside a terminal. |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

```bash theme={null}
oqoqo uploads cancel upl_9e04a6d2 --yes
```

**Notes**

Cancelling a cancelled upload returns it again. You can't cancel a completed upload; change or delete its resources instead.

## oqoqo resources delete

Permanently delete experiments and project resources, and everything that depends on them.

```bash theme={null}
oqoqo resources delete --targets-file <path> [flags]
```

**Plugin (MCP) tool:** [`delete_resources`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#delete_resources). With `--dry-run`: [`preview_delete_resources`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#preview_delete_resources).

> [!WARNING]
>
> 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**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--targets` | string | | The targets as an inline JSON array. |
| `--targets-file` | file path | | A file that holds the targets JSON array. |
| `--dry-run` | boolean | `false` | Show the plan, its `planHash`, its blockers, and the schedules it deletes or pauses. Change nothing. |
| `--plan-hash` | string | | The `planHash` from `--dry-run`. With `--yes`, refuse the deletion if the plan changed. |
| `--attempt-id` | string | | An ID you choose, so that a retry doesn't repeat the change. 16 to 100 characters. Without it, the CLI makes a new one for each call. |
| `--yes` | boolean | `false` | Skip interactive confirmation. Required with `--output json` or outside a terminal. |

Pass exactly one of `--targets` or `--targets-file`. Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#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`.

| `resourceType` | Names |
| - | - |
| `task`, `skill`, `mcp_server`, `cli`, `sdk`, `treatment` | The resource and all its versions, by ID or key. |
| `task_version`, `skill_version`, `mcp_server_version`, `cli_version`, `sdk_version` | One version. Add `version` with the version number. |
| `file`, `machine`, `experiment` | The resource, by ID only. |

**Examples**

Save the targets as `delete.json`:

```json theme={null}
[
  { "resourceType": "experiment", "id": "exp_8f2c41d0" },
  { "resourceType": "skill_version", "id": "skl_4be07a93", "version": 2 }
]
```

Preview the deletion, then delete with the same plan:

```bash theme={null}
oqoqo resources delete --targets-file ./delete.json --dry-run --output json
oqoqo resources delete --targets-file ./delete.json --plan-hash 9d1f0c6a2b --attempt-id delete-old-skill-2026-11-12 --yes --output json
```

**Result fields**

| Field | Description |
| - | - |
| `planHash` | With `--dry-run`: the plan's hash, to pass as `--plan-hash`. |
| `plan.summary` | With `--dry-run`: counts of the targets, the affected items, the stored files, the active runs it cancels first, and the blockers. |
| `plan.nodes` | With `--dry-run`: each item, with `action` set to `delete`, `cancel_then_delete`, or `block`. An experiment's own runs read **Experiment runs**. |
| `plan.schedules`, `plan.pausedSchedules` | With `--dry-run`: the schedules it deletes, and the schedules it pauses. |
| `job.deletionId` | Without `--dry-run`: the `del_` deletion ID. |

**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`](#oqoqo-deletions-status). When it finishes, Oqoqo pauses each active schedule that can no longer launch and marks it [**Needs attention**](https://docs.oqoqo.ai/experiments/schedules.md).

## oqoqo deletions status

Read the status of a resource deletion and why it failed.

```bash theme={null}
oqoqo deletions status <deletion-id> [flags]
```

**Plugin (MCP) tool:** [`get_resource_deletion`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#get_resource_deletion)

**Arguments**

| Argument | Description |
| - | - |
| `<deletion-id>` | Required. The `del_` deletion ID. |

Takes only the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

```bash theme={null}
oqoqo deletions status del_5a3c81f0 --project-id prj_4d7a20c5
```

**Result fields**

| Field | Description |
| - | - |
| `status` | `preview_ready`, `queued`, or `deleting` while the deletion runs. `completed`, `failed`, `failed_to_start`, `needs_attention`, and `cancelled_before_start` are final. Any other status reads `unknown`. |
| `failure` | On a failed deletion, a `code` and a `message`. |
| `attemptId`, `targets` | The deletion's attempt ID and targets. |

**Notes**

To resume a deletion that didn't finish, send the same targets with the same `--attempt-id` to `oqoqo resources delete`.

## Related

> [card] [oqoqo experiments](https://docs.oqoqo.ai/cli/experiments.md)
>
> Launch an experiment with the tasks and treatments you built.

> [card] [Tasks and rubrics](https://docs.oqoqo.ai/experiments/tasks.md)
>
> What makes a good task and rubric.

> [card] [Treatments (Toolsets)](https://docs.oqoqo.ai/experiments/treatments.md)
>
> Group tools into the sets you compare.

> [card] [oqoqo tags](https://docs.oqoqo.ai/cli/tags.md)
>
> Label resources and filter lists by tag.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.