# obss projects - Obss

CLI
obss projects
List, choose, inspect, create, rename, and delete Obss 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
obss projects use
, or pass
--project-id
on a single command.
Choose a project
has the full order the CLI follows.
obss projects list
List the projects in your organization and mark the current one.
obss
projects
list
[flags]
Plugin (MCP) tool:
get_project_context
Takes only the
global flags
.
Examples
obss
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.
obss projects current
Show the current project and why the CLI chose it.
obss
projects
current
[flags]
Plugin (MCP) tool:
get_project_context
Takes only the
global flags
.
Examples
obss
projects
current
Result fields
The same fields as
obss projects list
:
organization
,
projects
,
project
, and
projectSource
.
Notes
projectSource
is
preferred
for a project you saved with
obss projects use
, and
fallback
when Obss chose one because you saved none or can no longer open the saved one.
obss projects use
Save a project for this organization, so later commands use it until you choose another.
obss
projects
use
<
project-i
d
>
[flags]
Plugin (MCP) tool:
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
.
Examples
obss
projects
use
prj_4d7a20c5
Result fields
The same fields as
obss 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.
obss projects inspect
Show one project by its ID.
obss
projects
inspect
<
project-i
d
>
[flags]
Plugin (MCP) tool:
get_project_context
Arguments
Argument
Description
<project-id>
Required. The
prj_
ID of the project.
Takes only the
global flags
.
Examples
Read
updatedAt
before a rename:
obss
projects
inspect
prj_4d7a20c5
--output
json
Result fields
The same fields as
obss projects list
:
organization
,
projects
,
project
, and
projectSource
, which is
explicit
.
Notes
Inspecting a project doesn’t change the saved project.
obss projects create
Create a project in your organization.
obss
projects
create
--name
<
nam
e
>
--mutation-attempt-id
<
i
d
>
[flags]
Plugin (MCP) tool:
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
.
Examples
obss
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
obss projects use
to switch to it. Reusing an attempt ID for a different name fails with a conflict.
obss projects update
Rename a project.
obss
projects
update
<
project-i
d
>
--name
<
nam
e
>
[flags]
Plugin (MCP) tool:
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
obss projects inspect
. If the project changed since, the rename fails with
project_update_stale
.
Also takes the
global flags
.
Examples
obss
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.
obss projects delete
Permanently delete a project and everything in it.
obss
projects
delete
<
project-i
d
>
[flags]
Plugin (MCP) tool:
delete_project
. With
--dry-run
:
preview_delete_project
.
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 the command with
--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
Confirm without a prompt. Required with
--output json
or without a terminal.
Also takes the
global flags
.
Examples
Preview the deletion, then delete from a script:
obss
projects
delete
prj_9b13e6f2
--dry-run
--output
json
obss
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
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
obss deletions status
. Wait while it’s queued or deleting; otherwise send the same deletion again to resume it.
Next steps
obss catalog and resources
Create tasks, tools, and treatments.
Projects
Create and switch projects in the dashboard.
CLI reference
Global flags, output, exit codes, and conventions.
Sign-in and updates
catalog and resources
Powered by
This documentation is built and hosted on Mintlify, a developer documentation platform