confluence-bulk
Installation
SKILL.md
Confluence Bulk Skill
Bulk operations for Confluence content management at scale - updates, moves, deletions, labels, and permissions.
⚠️ PRIMARY USE CASE
This skill performs bulk operations on multiple pages. Use for:
- Updating multiple pages simultaneously
- Bulk labeling/unlabeling content
- Moving many pages between spaces
- Bulk permission changes
- Mass deletion with dry-run preview
When to Use / When NOT to Use
| Use This Skill | Use Instead |
|---|---|
| Update 10+ pages | - |
| Bulk label operations | - |
| Move pages between spaces | - |
| Bulk delete with preview | - |
| Single page operations | confluence-page |
| Search for pages | confluence-search |
| Single label add/remove | confluence-label |
Risk Levels
| Operation | Risk | Notes |
|---|---|---|
| Bulk label add | ⚠️ | Can be undone |
| Bulk label remove | ⚠️ | Can be undone |
| Bulk update | ⚠️⚠️ | Modifies content |
| Bulk move | ⚠️⚠️ | Changes hierarchy |
| Bulk permission change | ⚠️⚠️ | Access control |
| Bulk delete | ⚠️⚠️⚠️ | DESTRUCTIVE - Use dry-run first |
Always use --dry-run for destructive operations!
When to Use This Skill
Use this skill when you need to:
- Update multiple pages with the same change
- Add or remove labels from many pages at once
- Move pages between spaces or under different parents
- Delete multiple pages with preview capability
- Change permissions on many pages simultaneously
- Execute operations with dry-run preview before making changes
- Handle partial failures gracefully with progress tracking
Scale guidance:
- 5-10 pages: Run directly, no special options needed
- 50-100 pages: Use
--dry-runfirst, then execute - 500+ pages: Consider off-peak hours; use
--batch-sizefor label add operations
Quick Start
# Preview before making changes
confluence bulk label add --cql "space = DOCS AND type = page" --labels "approved" --dry-run
# Execute the labeling
confluence bulk label add --cql "space = DOCS AND type = page" --labels "approved"
# Bulk delete with preview
confluence bulk delete --cql "space = ARCHIVE AND created < '2023-01-01'" --dry-run
CLI Commands
| Command | Purpose | Risk | Example |
|---|---|---|---|
confluence bulk label add |
Add labels to pages | ⚠️ | --cql "..." --labels "tag1,tag2" |
confluence bulk label remove |
Remove labels from pages | ⚠️ | --cql "..." --labels "old-tag" |
confluence bulk update |
Update page properties | ⚠️⚠️ | --cql "..." --title-prefix "[Archive]" --title-suffix " (Old)" |
confluence bulk move |
Move pages to new location | ⚠️⚠️ | --cql "..." --target-space NEWSPACE |
confluence bulk delete |
Delete pages permanently | ⚠️⚠️⚠️ | --cql "..." --dry-run |
confluence bulk permission |
Change page permissions | ⚠️⚠️ | --cql "..." --add-group GROUP / --remove-group GROUP / --add-user USERID / --remove-user USERID |
Common Options
All commands support these options:
| Option | Purpose | When to Use |
|---|---|---|
--dry-run |
Preview changes | Always use for ⚠️⚠️+ operations |
--yes / -y |
Skip confirmation | Scripted automation |
--max-pages N |
Limit scope (default: 100) | Testing, large operations |
--batch-size N |
Control batching (label add only) | 500+ pages or rate limits (not all commands support this) |
--output json |
JSON output | Scripting, pipelines |
Examples
Bulk Label Operations
# Add labels to all pages in a space
confluence bulk label add --cql "space = DOCS AND type = page" --labels "documentation"
# Add multiple labels
confluence bulk label add --cql "space = DOCS AND label = 'api'" --labels "reviewed,approved"
# Remove labels
confluence bulk label remove --cql "space = ARCHIVE" --labels "active,current"
# Preview first
confluence bulk label add --cql "space = DOCS" --labels "new-tag" --dry-run
Bulk Move Operations
# Move pages to different space
confluence bulk move --cql "space = OLD AND type = page" --target-space NEW --dry-run
# Move under specific parent
confluence bulk move --cql "label = 'archive-ready'" --target-parent 12345 --dry-run
# Execute after preview
confluence bulk move --cql "space = OLD" --target-space NEW --yes
Bulk Delete (DESTRUCTIVE)
# ALWAYS preview first with dry-run
confluence bulk delete --cql "space = CLEANUP AND type = page" --dry-run
# Delete old content
confluence bulk delete --cql "space = ARCHIVE AND lastModified < '2022-01-01'" --dry-run
# Execute deletion (after confirming dry-run output)
confluence bulk delete --cql "space = CLEANUP" --yes
# Limit scope for safety
confluence bulk delete --cql "space = CLEANUP" --max-pages 50 --dry-run
Safety features:
--dry-runshows exactly what will be deleted before making changes- Confirmation required by default
- Default
--max-pages 100prevents accidental mass deletion - Per-page error tracking with summary of failures
Bulk Permission Changes
# Add group to page permissions
confluence bulk permission --cql "space = INTERNAL" --add-group "engineering" --dry-run
# Remove group from page permissions
confluence bulk permission --cql "space = INTERNAL" --remove-group "contractors" --dry-run
# Add user to page permissions
confluence bulk permission --cql "label = 'team-docs'" --add-user "user123" --dry-run
# Remove user from permissions
confluence bulk permission --cql "label = 'sensitive'" --remove-user "contractor123" --dry-run
Permission options:
--add-group GROUP- Add a group to page permissions--remove-group GROUP- Remove a group from page permissions--add-user USERID- Add a user to page permissions--remove-user USERID- Remove a user from page permissions
Parameter Tuning Guide
How many pages?
| Page Count | Recommended Setup |
|---|---|
| <50 | Defaults are fine |
| 50-500 | --dry-run first, then execute |
| 500-1,000 | Use --batch-size 100 for label add; run off-peak for other commands |
| 1,000+ | Use --batch-size 50 for label add; run off-peak for other commands |
Getting rate limit (429) errors?
- For label add: Reduce batch size with
--batch-size 25 - For other commands: Run during off-peak hours, use
--max-pagesto limit scope
Exit Codes
| Code | Meaning |
|---|---|
| 0 | All operations successful |
| 1 | Some failures or validation error |
| 2 | All operations failed |
| 130 | Cancelled by user (Ctrl+C) |
Troubleshooting
| Error | Solution |
|---|---|
No pages found |
Verify CQL query returns results |
Permission denied |
Check space/page permissions |
Rate limit (429) |
Reduce --batch-size or run during off-peak |
Invalid CQL |
Test CQL in Confluence search first |
Page locked |
Page may be being edited; retry later |
Related Skills
- confluence-page: Single-page operations
- confluence-label: Individual label management
- confluence-search: Find pages with CQL queries
- confluence-permission: Single-page permission changes
Related skills
More from grandcamel/confluence-assistant-skills
confluence-space
Manage Confluence spaces - create, list, update, delete, and configure spaces. ALWAYS use when user wants to work with spaces (not individual pages).
1confluence-watch
Content watching and notifications. ALWAYS use when user wants to follow content or manage notifications.
1confluence-label
Manage content labels - add, remove, and search by labels. ALWAYS use when user wants to tag, label, or categorize content.
1confluence-page
Manage Confluence pages and blog posts - create, read, update, delete, copy, move, and version control. ALWAYS use when user wants to work with page content, create pages, update pages, or manage page versions.
1confluence-ops
Cache management, API diagnostics, and operational utilities. Use when optimizing performance, managing cache, diagnosing API issues, or troubleshooting Confluence connectivity.
1confluence-jira
JIRA integration - embed issues, create links between products. ALWAYS use when user wants to connect Confluence and JIRA.
1