Skip to main content
A tag is a project label with a stable tag_ ID that helps you find records again. It never changes what a record does or how a run uses it.

Refer to tags and records

Name a tag by its tag_ ID or by its name in any case (Flaky and flaky are the same tag). Quote a name with spaces. Name a record by its public ID: Tags go on the record, not a version, so new versions keep them. Agents, runs, frictions, and projects have no tags.

obss tags list

List the project’s tags, with each one’s tag_ ID and how many records of each kind have it.
Plugin (MCP) tool: list_tags Flags Also takes the global flags. Examples List the project’s tags:
Result fields

obss tags add

Add tags to up to 100 records at once. A new name creates the tag.
Plugin (MCP) tool: update_tags Arguments Flags Also takes the global flags. Examples Tag a task and an experiment:
Add a tag with a space in its name:
Result fields Notes You can run the command again safely: a record that already has a tag keeps it. A change that goes over a limit changes nothing and fails with tag_limit_exceeded, which names the limit.

obss tags remove

Remove tags from up to 100 records at once. The tags stay in the project.
Plugin (MCP) tool: update_tags Arguments Flags Also takes the global flags. Examples Remove a tag from a task:
Result fields records and createdTags, as in obss tags add: each record’s id, kind, and tags after the change. Notes You can run the command again safely. To remove a tag from every record and from the project, use obss tags delete.

obss tags rename

Rename a tag everywhere. Its tag_ ID stays, so every record keeps it.
Plugin (MCP) tool: rename_tag Arguments Flags Also takes the global flags. Examples Rename a tag:
Result fields The result has the renamed tag, with its id, name, usage, createdAt, and updatedAt. Notes A name that another tag already has, in any case, fails with tag_name_taken. A tag that changed since you read it fails with tag_changed, so run the command again.

obss tags delete

Delete a tag from the project and every record. The records stay.
Plugin (MCP) tool: delete_tag
This can’t be undone. In a terminal, the CLI says how many records have the tag and asks you to confirm. With --output json, or without a terminal, pass --yes.
Arguments Flags Also takes the global flags. Examples Delete a tag in a script:
Result fields Notes A tag the project doesn’t have fails with tag_not_found. When you delete a tagged task, tool, treatment, or experiment, its tags stay in the project.

Filter lists by tag

obss catalog list and obss experiments list take two tag filters. A tag the project doesn’t have fails with tag_not_found, not an empty list, and details.tags names it. Each returned record lists its tags.

Names and limits

Next steps