> ## 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 projects

> List, choose, inspect, create, rename, and delete Oqoqo projects from the CLI, and set the project that later commands use.

A project holds your tasks, tools, treatments, and experiments. Most commands work in one project: save it with `oqoqo projects use`, or pass `--project-id` on a single command. [Choose a project](https://docs.oqoqo.ai/cli/overview.md#choose-a-project) has the full order the CLI follows.

## oqoqo projects list

List the projects in your organization and mark the current one.

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

**Plugin (MCP) tool:** [`get_project_context`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#get_project_context)

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

**Examples**

```bash theme={null}
oqoqo projects list --output json
```

**Result fields**

| Field | Description |
| - | - |
| `organization` | Your organization's `id` and `name`. |
| `projects` | The projects in the organization. |
| `project` | The current project, or `null`. |
| `projectSource` | Why the CLI chose it: `explicit`, `preferred`, or `fallback`. |

**Notes**

In text output, `*` marks the current project.

## oqoqo projects current

Show the current project and why the CLI chose it.

```bash theme={null}
oqoqo projects current [flags]
```

**Plugin (MCP) tool:** [`get_project_context`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#get_project_context)

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

**Examples**

```bash theme={null}
oqoqo projects current
```

**Result fields**

The same fields as [`oqoqo projects list`](#oqoqo-projects-list): `organization`, `projects`, `project`, and `projectSource`.

**Notes**

`projectSource` is `preferred` for a project you saved with `oqoqo projects use`, and `fallback` when Oqoqo chose one because you saved none or can no longer open the saved one.

## oqoqo projects use

Save a project for this organization, so later commands use it until you choose another.

```bash theme={null}
oqoqo projects use <project-id> [flags]
```

**Plugin (MCP) tool:** [`get_project_context`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#get_project_context). The plugin saves no project, so pass `project_id` on each call.

**Arguments**

| Argument | Description |
| - | - |
| `<project-id>` | Required. The `prj_` ID of the project to use. |

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

**Examples**

```bash theme={null}
oqoqo projects use prj_4d7a20c5
```

**Result fields**

The same fields as [`oqoqo projects list`](#oqoqo-projects-list): `organization`, `projects`, `project`, and `projectSource`.

**Notes**

A project you can't open fails with `project_not_found` and isn't saved. To run one command in another project, pass `--project-id` instead.

## oqoqo projects inspect

Show one project by its ID.

```bash theme={null}
oqoqo projects inspect <project-id> [flags]
```

**Plugin (MCP) tool:** [`get_project_context`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#get_project_context)

**Arguments**

| Argument | Description |
| - | - |
| `<project-id>` | Required. The `prj_` ID of the project. |

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

**Examples**

Read `updatedAt` before a rename:

```bash theme={null}
oqoqo projects inspect prj_4d7a20c5 --output json
```

**Result fields**

The same fields as [`oqoqo projects list`](#oqoqo-projects-list): `organization`, `projects`, `project`, and `projectSource`, which is `explicit`.

**Notes**

Inspecting a project doesn't change the saved project.

## oqoqo projects create

Create a project in your organization.

```bash theme={null}
oqoqo projects create --name <name> --mutation-attempt-id <id> [flags]
```

**Plugin (MCP) tool:** [`manage_project`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#manage_project)

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--name` | string | | Required. The project name, up to 120 characters. |
| `--mutation-attempt-id` | string | | Required. An ID you choose, so that a retry doesn't repeat the change. Up to 100 characters. |

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

**Examples**

```bash theme={null}
oqoqo projects create --name "Checkout agents" --mutation-attempt-id create-checkout-agents-01
```

**Result fields**

| Field | Description |
| - | - |
| `operation` | `created`. |
| `project` | The new project, with its `projectId`. |

**Notes**

The new project doesn't become the saved project, so run `oqoqo projects use` to switch to it. Reusing an attempt ID for a different name fails with a conflict.

## oqoqo projects update

Rename a project.

```bash theme={null}
oqoqo projects update <project-id> --name <name> [flags]
```

**Plugin (MCP) tool:** [`manage_project`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#manage_project)

**Arguments**

| Argument | Description |
| - | - |
| `<project-id>` | Required. The `prj_` ID of the project to rename. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--name` | string | | Required. The new name, up to 120 characters. |
| `--expected-updated-at` | string | | The project's ISO 8601 `updatedAt` from `oqoqo projects inspect`. If the project changed since, the rename fails with `project_update_stale`. |

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

**Examples**

```bash theme={null}
oqoqo projects update prj_4d7a20c5 --name "Checkout agents (Q4)" --expected-updated-at 2026-11-10T16:42:05Z
```

**Notes**

Without `--expected-updated-at`, the rename overwrites any change made after you read the project, so always pass it from a script or an AI assistant.

## oqoqo projects delete

Permanently delete a project and everything in it.

```bash theme={null}
oqoqo projects delete <project-id> [flags]
```

**Plugin (MCP) tool:** [`delete_project`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#delete_project). With `--dry-run`: [`preview_delete_project`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#preview_delete_project).

> [!WARNING]
>
> This stops the project's running experiments, then deletes its tasks, files, machines, tools, treatments, agent settings, experiments, schedules, runs, Evals, and Insights. You can't undo it, so run `--dry-run` first to preview what it removes.

**Arguments**

| Argument | Description |
| - | - |
| `<project-id>` | Required. The `prj_` ID of the project to delete. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--dry-run` | boolean | `false` | Show what the deletion stops, removes, and is blocked by, without changing anything. |
| `--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**

Preview the deletion, then delete from a script:

```bash theme={null}
oqoqo projects delete prj_9b13e6f2 --dry-run --output json
oqoqo projects delete prj_9b13e6f2 --yes --output json
```

**Result fields**

| Field | Description |
| - | - |
| `impact` | With `--dry-run`: a count of each kind of item the deletion removes, and `total`. |
| `runningExperiments` | With `--dry-run`: the experiments it stops first. |
| `customAgents` | With `--dry-run`: the organization's custom agents, which stay. |
| `blockers` | With `--dry-run`: what blocks the deletion. |
| `status`, `projectId`, `projectName` | On success: `deleted`, and the project's ID and name. |
| `stoppedExperiments`, `deletedAt` | On success: the experiments it stopped, and when it deleted the project. |

**Notes**

In a terminal, the CLI shows what the deletion stops and removes, and asks you to confirm. With `--output json`, or without a terminal, pass `--yes`. Custom agents belong to the organization, so the deletion keeps them.

A blocker makes the command fail with `project_deletion_blocked`, without a prompt:

| Blocker `code` | What to do |
| - | - |
| `last_project` | You can't delete the organization's only project. Create another project first. |
| `experiment_publication_requires_unpublish` | [Unpublish](https://docs.oqoqo.ai/cli/experiments.md#oqoqo-experiments-publications-unpublish) every public experiment in the project, and wait for cleanup to finish. |
| `resource_deletion_requires_resolution` | A resource deletion in the project hasn't finished. Read the deletion that `deletionIds` names with [`oqoqo deletions status`](https://docs.oqoqo.ai/cli/catalog#oqoqo-deletions-status). Wait while it's queued or deleting; otherwise send the same deletion again to resume it. |

## Related

> [card] [oqoqo catalog, resources, and uploads](https://docs.oqoqo.ai/cli/catalog.md)
>
> Create tasks, tools, and treatments.

> [card] [Projects](https://docs.oqoqo.ai/setup/projects.md)
>
> Create and switch projects in the dashboard.

> [card] [CLI reference](https://docs.oqoqo.ai/cli/overview.md)
>
> Global flags, output, exit codes, and conventions.


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