Issue labels

Use labels to classify related Cortex Issues across Modules. Labels help people and agents retrieve work. They do not change priority, assignment, readiness, permissions, or execution order.

Label identity

A label belongs to one Account. Its stable label_... ID remains the same when you rename the label or change its color.

Label names are unique within the Account. A name can contain lowercase letters and digits, with single hyphens between words. The name must be 1 to 40 characters long. An optional color uses a lowercase six-digit hex value such as #dc2626.

Create and find labels

These examples use the Socra CLI with Cortex installed and manage labels in your authenticated Account.

Create a label without a color:

socra cortex label create --name security

Add a color when it helps a visual interface distinguish the label. Quote the value so the shell does not treat # as a comment:

socra cortex label create --name customer-report --color '#2563eb'

List the Account's labels:

socra cortex label list

Search label names without regard to case:

socra cortex label list --query report

Use socra cortex label get LABEL_ID when you need the current name and color for one stable ID.

Apply labels to Issues

Replace MODULE_NAME with the name of the Module that will own the Issue. Add labels when you create it:

socra cortex issue create \
  --module MODULE_NAME \
  --title "Review access failure" \
  --description "Find the cause and record the verified fix." \
  --labels security,customer-report

The CLI accepts label names or label_... IDs. It resolves names to stable IDs before it sends the request.

For an existing Issue, use its ID as ISSUE_ID below.

Complete set: --labels replaces every label on the Issue. Include each label that must remain. Pass --labels "" to remove all labels.

Replace the complete label set on an existing Issue:

socra cortex issue update ISSUE_ID --labels security,customer-report

Cortex records a labels_changed entry in the Issue timeline when the set changes. Issue reads include each label's current name and color.

Filter Issues by label

List Issues that carry one label:

socra cortex issue list --label security

Combine the label with a text search or another supported Issue filter:

socra cortex issue search --query access --label security

The CLI accepts a label name or ID for either command. The API accepts the stable label ID.

Rename or recolor a label

Use the label ID returned by socra cortex label list as LABEL_ID:

socra cortex label update LABEL_ID --name product-security --color '#dc2626'

Existing Issues keep the label because the ID does not change. Clear only the color with --remove-color.

Delete an unused label

Cortex refuses to delete a label while any Issue uses it. Find those Issues first:

socra cortex issue list --label LABEL_ID

Check every page of results, including closed Issues. Update each Issue with the complete label set that should remain. Then delete the unused label:

socra cortex label delete LABEL_ID

Deletion removes the label registry entry. Creating a label with the same name later produces a new stable ID.

Use labels through MCP or the API

The MCP server exposes label_list, label_get, label_create, label_update, and label_delete. Its Issue tools accept label IDs. The Cortex API reference describes the same Account-scoped label resource and Issue fields.