---
title: "Issue labels"
canonical: https://workspace.socra.com/docs/cortex/guides/issue-labels
---

# 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](/docs/cortex/reference/cli) and manage labels in your authenticated Account.

Create a label without a color:

```bash
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:

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

List the Account's labels:

```bash
socra cortex label list
```

Search label names without regard to case:

```bash
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:

```bash
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:

```bash
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:

```bash
socra cortex issue list --label security
```

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

```bash
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`:

```bash
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:

```bash
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:

```bash
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](/docs/cortex/reference/api) describes the same Account-scoped label resource and Issue fields.