Labels

Labels

Add, remove, and manage labels on Confluence pages.

Prerequisites

• Authenticated profile (atlcli auth login)
• Space permission: Edit permission to add/remove labels

Overview

Labels help organize and categorize pages. Use them for:

• Content categorization (e.g., api, tutorial, reference)
• Review status (e.g., needs-review, approved)
• Team ownership (e.g., team-backend, team-frontend)

List Labels

View labels on a page:

atlcli wiki page label list --id 12345

Output:

api
documentation
v2

Add Labels

Add one or more labels (labels are positional arguments):

# Single label
atlcli wiki page label add api --id 12345

# Multiple labels
atlcli wiki page label add api documentation v2 --id 12345

Remove Labels

atlcli wiki page label remove deprecated --id 12345

Bulk Label Operations

Add or remove labels from multiple pages using CQL:

# Add label to pages matching CQL (preview first)
atlcli wiki page label add archived --cql "space=OLD" --dry-run

# Add label (requires --confirm)
atlcli wiki page label add archived --cql "space=OLD" --confirm

# Remove label from pages matching CQL
atlcli wiki page label remove draft --cql "label=draft AND space=DEV" --confirm

Options:

Flag	Description
--id	Page ID for single-page operations
--cql	CQL query for bulk operations
--dry-run	Preview what would be affected
--confirm	Required for bulk operations

Find Pages by Label

Search for pages with specific labels:

# All pages with label
atlcli wiki search --label api

# In specific space
atlcli wiki search --label api --space TEAM

# Multiple labels (AND)
atlcli wiki search --label "api,v2"

Sync Behavior

atlcli syncs labels as part of page metadata:

In Frontmatter

---
atlcli:
  id: "12345"
  title: "API Reference"
  labels:
    - api
    - documentation
    - v2
---

# API Reference
...

During Pull

Labels are included in frontmatter when pulling:

atlcli wiki docs pull ./docs

During Push

atlcli syncs labels from frontmatter to Confluence:

atlcli wiki docs push ./docs

Label Changes

Removing a label from frontmatter will remove it from Confluence on push.

JSON Output

atlcli wiki page label list --id 12345 --json

{
  "schemaVersion": "1",
  "pageId": "12345",
  "labels": [
    {"name": "api", "prefix": "global"},
    {"name": "documentation", "prefix": "global"},
    {"name": "v2", "prefix": "global"}
  ],
  "total": 3
}

Label Naming

• Labels are case-insensitive (API = api)
• Use hyphens for multi-word labels (api-reference)
• Avoid spaces (use hyphens instead)
• Maximum 255 characters

Use Cases

Content Lifecycle

# Mark for review
atlcli wiki page label add needs-review --id 12345

# After review
atlcli wiki page label remove needs-review --id 12345
atlcli wiki page label add approved --id 12345

Team Organization

# Assign ownership
atlcli wiki page label add team-backend component-api --id 12345

# Find team's pages
atlcli wiki search --label team-backend --space DOCS

Version Tracking

# Mark version-specific docs
atlcli wiki page label add v2.0 --id 12345

# Find all v2 docs
atlcli wiki search --label "v2.0"

Related Topics

• Search - Find pages by label
• Audit - Check for missing required labels
• Sync - Labels in frontmatter sync behavior