# obss tags - Obss

CLI
obss tags
List, add, remove, rename, and delete tags on tasks, files, machines, tools, treatments, and experiments, and filter lists by tag.
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:
Prefix
Record
tsk_
Task. Use the task ID, not a task version ID.
fld_
File
env_
Machine
skl_
,
mcp_
,
cli_
,
sdk_
Skill, MCP server, CLI, or SDK
trt_
Treatment (toolset)
exp_
Experiment
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.
obss
tags
list
[flags]
Plugin (MCP) tool:
list_tags
Flags
Flag
Type
Default
Description
--query
string
Only tags whose name contains this text, up to 40 characters.
Also takes the
global flags
.
Examples
List the project’s tags:
obss
tags
list
Result fields
Field
Meaning
id
,
name
The tag’s
tag_
ID and name
usage
How many records have the tag, in total and by kind
createdAt
,
updatedAt
When the tag was created and last changed. Rename and delete check
updatedAt
.
obss tags add
Add tags to up to 100 records at once. A new name creates the tag.
obss
tags
add
<
ta
g
>
...
--to
<
record-id
s
>
[flags]
Plugin (MCP) tool:
update_tags
Arguments
Argument
Description
<tag>...
Required. Up to 20 tag names or
tag_
IDs.
Flags
Flag
Type
Default
Description
--to
string
Required. Up to 100 comma-separated
record IDs
.
Also takes the
global flags
.
Examples
Tag a task and an experiment:
obss
tags
add
needs-review
regression
--to
tsk_3a91c7e2,exp_8f2c41d0
Add a tag with a space in its name:
obss
tags
add
"release 11"
--to
trt_51be0c9a
Result fields
Field
Meaning
records
Each record’s
id
,
kind
, and all its
tags
after the change
createdTags
The tags this change created, each with
id
and
name
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.
obss
tags
remove
<
ta
g
>
...
--from
<
record-id
s
>
[flags]
Plugin (MCP) tool:
update_tags
Arguments
Argument
Description
<tag>...
Required. Up to 20 tag names or
tag_
IDs.
Flags
Flag
Type
Default
Description
--from
string
Required. Up to 100 comma-separated
record IDs
.
Also takes the
global flags
.
Examples
Remove a tag from a task:
obss
tags
remove
regression
--from
tsk_3a91c7e2
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.
obss
tags
rename
<
ta
g
>
<
nam
e
>
[flags]
Plugin (MCP) tool:
rename_tag
Arguments
Argument
Description
<tag>
Required. The tag’s
tag_
ID or current name.
<name>
Required. The new name.
Flags
Flag
Type
Default
Description
--expected-updated-at
ISO 8601 date-time
The tag’s current
updatedAt
The
updatedAt
from
obss tags list
. Refused if the tag changed since.
Also takes the
global flags
.
Examples
Rename a tag:
obss
tags
rename
needs-review
"needs review"
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.
obss
tags
delete
<
ta
g
>
[flags]
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
Argument
Description
<tag>
Required. The tag’s
tag_
ID or name.
Flags
Flag
Type
Default
Description
--expected-updated-at
ISO 8601 date-time
The tag’s current
updatedAt
The
updatedAt
from
obss tags list
. Refused if the tag changed since.
--yes
boolean
false
Confirm without a prompt. Required with
--output json
or without a terminal.
Also takes the
global flags
.
Examples
Delete a tag in a script:
obss
tags
delete
regression
--yes
--output
json
Result fields
Field
Meaning
tag
The deleted tag’s
id
and
name
removedFrom
How many records had the tag
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.
Flag
Type
Description
--tag
string
Comma-separated tag names or
tag_
IDs. Records with any of them.
--untagged
boolean
Records with no tags. With
--tag
, records with any of those tags or none.
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.
obss
catalog
list
--tag
needs-review
obss
experiments
list
--tag
release-11,release-12
obss
catalog
list
--untagged
Names and limits
Rule
Limit
Name length
1 to 40 characters
Characters
Any, except a comma and control characters. A name cannot look like a tag ID (
tag_…
).
Spaces
Spaces at the start and end are removed. Two or more spaces become one.
Tags on one record
20
Tags in one project
500
Records in one change
100
Tags named in one change or one filter
20
Next steps
Tags
Add and filter tags in the dashboard.
obss catalog and resources
Find tagged tasks, tools, and treatments.
obss experiments
Find tagged experiments.
IDs and limits
Every ID prefix and product limit.
evals and insights
data
Powered by
This documentation is built and hosted on Mintlify, a developer documentation platform