@bestend/confluence-cli 1.16.0 → 2.0.0

package/README.md

@@ -1,5 +1,7 @@
 # Confluence CLI
 
+> **Fork**: [`@bestend/confluence-cli`](https://github.com/bestend/confluence-cli) — forked from [`pchuri/confluence-cli`](https://github.com/pchuri/confluence-cli) (based on upstream v1.27.1)
+
 A powerful command-line interface for Atlassian Confluence that allows you to read, search, and manage your Confluence content from the terminal.
 
 ## Features
@@ -11,23 +13,69 @@ A powerful command-line interface for Atlassian Confluence that allows you to re
 - ✏️ **Create pages** - Create new pages with support for Markdown, HTML, or Storage format
 - 📝 **Update pages** - Update existing page content and titles
 - 🗑️ **Delete pages** - Delete (or move to trash) pages by ID or URL
-- 📎 **Attachments** - List or download page attachments
+- 📎 **Attachments** - List, download, upload, or delete page attachments
+- 🏷️ **Properties** - List, get, set, and delete content properties (key-value metadata)
 - 💬 **Comments** - List, create, and delete page comments (footer or inline)
 - 📦 **Export** - Save a page and its attachments to a local folder
 - 🛠️ **Edit workflow** - Export page content for editing and re-import
+- 🔀 **Profiles** - Manage multiple Confluence instances with named configuration profiles
+- 🔒 **Read-only mode** - Profile-level write protection for safe AI agent usage
 - 🔧 **Easy setup** - Simple configuration with environment variables or interactive setup
 
+## Fork-specific Features
+
+This fork adds the following features on top of upstream:
+
+### Context Path Auto-detection
+
+Upstream hardcodes `/wiki` as the context path, which breaks on Confluence Server/Data Center instances with custom context paths (or no context path). This fork auto-detects the context path from the `_links.context` field in API responses.
+
+### Storage Format Sanitization & XML Validation
+
+- **`--sanitize-storage`** (default: on) — Auto-escapes raw `&` characters to `&` before sending, preventing XML parse errors
+- **`--validate-storage`** — Optionally validates storage content as well-formed XML before sending, with line/column error reporting via `fast-xml-parser`
+
+### `create --parent` Option
+
+Create a child page directly with `--parent <pageId>` on the `create` command, without needing the separate `create-child` command.
+
+```bash
+confluence create "Child Page" SPACEKEY --parent 12345 -c "Content here"
+```
+
+### Spaces URL Parsing
+
+Supports `/spaces/SPACEKEY/pages/ID/Title` URL format in addition to upstream's `/pages/ID` pattern.
+
+### `<hr/>` Tag Removal
+
+Removes `<hr/>` tags from Confluence storage format output during markdown conversion, since Confluence does not use horizontal rules.
+
 ## Installation
 
+### npm
+
 ```bash
-npm install -g @bestend/confluence-cli@1.15.2
+npm install -g @bestend/confluence-cli
 ```
 
 Or run directly with npx:
 ```bash
-npx @bestend/confluence-cli@1.15.2
+npx @bestend/confluence-cli
+```
+
+## Claude Code AI Skills
+
+If you use [Claude Code](https://claude.ai/code) or any AI agent that reads `.claude/skills/`, install the skill documentation so the agent understands all confluence-cli commands automatically.
+
+Run this from your project root after installing confluence-cli:
+
+```bash
+confluence install-skill
 ```
 
+This creates `.claude/skills/confluence/SKILL.md` in your current directory. Claude Code picks it up automatically and can help you with any confluence-cli command.
+
 ## Quick Start
 
 1. **Initialize configuration:**
@@ -67,7 +115,7 @@ npx @bestend/confluence-cli@1.15.2
 confluence init
 ```
 
-The wizard helps you choose the right API endpoint and authentication method. It recommends `/wiki/rest/api` for Atlassian Cloud domains (e.g., `*.atlassian.net`) and `/rest/api` for self-hosted/Data Center instances, then prompts for Basic (email + token) or Bearer authentication.
+The wizard helps you choose the right API endpoint and authentication method. It recommends `/wiki/rest/api` for Atlassian Cloud domains (e.g., `*.atlassian.net`) and `/rest/api` for self-hosted/Data Center instances, then prompts for Basic (email/username + token/password) or Bearer authentication.
 
 ### Option 2: Non-interactive Setup (CLI Flags)
 
@@ -83,6 +131,26 @@ confluence init \
   --token "your-api-token"
 ```
 
+**Scoped API token** (recommended for agents — least privilege):
+```bash
+# Replace <your-cloud-id> with your actual Cloud ID
+confluence init \
+  --domain "api.atlassian.com" \
+  --api-path "/ex/confluence/<your-cloud-id>/wiki/rest/api" \
+  --auth-type "basic" \
+  --email "user@example.com" \
+  --token "your-scoped-token"
+```
+
+**Named profile** (save to a specific profile):
+```bash
+confluence --profile staging init \
+  --domain "staging.example.com" \
+  --api-path "/rest/api" \
+  --auth-type "bearer" \
+  --token "your-personal-access-token"
+```
+
 **Hybrid mode** (some fields provided, rest via prompts):
 ```bash
 # Domain and token provided, will prompt for auth method and email
@@ -96,30 +164,62 @@ confluence init --email "user@example.com" --token "your-api-token"
 - `-d, --domain <domain>` - Confluence domain (e.g., `company.atlassian.net`)
 - `-p, --api-path <path>` - REST API path (e.g., `/wiki/rest/api`)
 - `-a, --auth-type <type>` - Authentication type: `basic` or `bearer`
-- `-e, --email <email>` - Email for basic authentication
-- `-t, --token <token>` - API token
+- `-e, --email <email>` - Email or username for basic authentication
+- `-t, --token <token>` - API token or password
+- `--read-only` - Enable read-only mode (blocks all write operations)
 
 ⚠️ **Security note:** While flags work, storing tokens in shell history is risky. Prefer environment variables (Option 3) for production environments.
 
 ### Option 3: Environment Variables
 ```bash
 export CONFLUENCE_DOMAIN="your-domain.atlassian.net"
-export CONFLUENCE_API_TOKEN="your-api-token"
-export CONFLUENCE_EMAIL="your.email@example.com"  # required when using basic auth
+export CONFLUENCE_API_TOKEN="your-api-token"      # or password for on-premise (alias: CONFLUENCE_PASSWORD)
+export CONFLUENCE_EMAIL="your.email@example.com"  # required for basic auth (alias: CONFLUENCE_USERNAME for on-premise)
 export CONFLUENCE_API_PATH="/wiki/rest/api"         # Cloud default; use /rest/api for Server/DC
 # Optional: set to 'bearer' for self-hosted/Data Center instances
 export CONFLUENCE_AUTH_TYPE="basic"
+# Optional: select a named profile (overridden by --profile flag)
+export CONFLUENCE_PROFILE="default"
+```
+
+**Scoped API token** (recommended for agents):
+```bash
+export CONFLUENCE_DOMAIN="api.atlassian.com"
+export CONFLUENCE_API_PATH="/ex/confluence/<your-cloud-id>/wiki/rest/api"
+export CONFLUENCE_AUTH_TYPE="basic"
+export CONFLUENCE_EMAIL="user@example.com"
+export CONFLUENCE_API_TOKEN="your-scoped-token"
 ```
 
 `CONFLUENCE_API_PATH` defaults to `/wiki/rest/api` for Atlassian Cloud domains and `/rest/api` otherwise. Override it when your site lives under a custom reverse proxy or on-premises path. `CONFLUENCE_AUTH_TYPE` defaults to `basic` when an email is present and falls back to `bearer` otherwise.
 
+**Read-only mode** (recommended for AI agents):
+```bash
+export CONFLUENCE_READ_ONLY=true
+```
+When set, all write operations (`create`, `update`, `delete`, etc.) are blocked at the CLI level. The environment variable overrides the profile's `readOnly` setting.
+
 ### Getting Your API Token
 
+**Atlassian Cloud:**
 1. Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)
 2. Click "Create API token"
 3. Give it a label (e.g., "confluence-cli")
 4. Copy the generated token
 
+**Atlassian Cloud — Scoped API Token** (recommended for agents and automation):
+
+Scoped tokens restrict access to specific Atlassian products and permissions, following the principle of least privilege. They use a different API gateway (`api.atlassian.com`) instead of your site domain.
+
+1. Create a scoped token in your [Atlassian Admin settings](https://admin.atlassian.com)
+2. Find your Cloud ID by visiting `https://<your-site>.atlassian.net/_edge/tenant_info`
+3. Configure with:
+   - **Domain:** `api.atlassian.com`
+   - **API path:** `/ex/confluence/<your-cloud-id>/wiki/rest/api`
+   - **Auth type:** `basic` (email + scoped token)
+
+**On-premise / Data Center:** Use your Confluence username and password for basic authentication.
+
 ## Usage
 
 ### Read a Page
@@ -160,6 +260,48 @@ confluence attachments 123456789 --pattern "*.png" --limit 5
 confluence attachments 123456789 --pattern "*.png" --download --dest ./downloads
 ```
 
+### Upload Attachments
+```bash
+# Upload a single attachment
+confluence attachment-upload 123456789 --file ./report.pdf
+
+# Upload multiple files with a comment
+confluence attachment-upload 123456789 --file ./a.pdf --file ./b.png --comment "v2"
+
+# Replace an existing attachment by filename
+confluence attachment-upload 123456789 --file ./diagram.png --replace
+```
+
+### Delete Attachments
+```bash
+# Delete an attachment by ID
+confluence attachment-delete 123456789 998877
+
+# Skip confirmation
+confluence attachment-delete 123456789 998877 --yes
+```
+
+### Content Properties
+```bash
+# List all properties on a page
+confluence property-list 123456789
+
+# Get a specific property
+confluence property-get 123456789 my-key
+
+# Set a property (creates or updates with auto-versioning)
+confluence property-set 123456789 my-key --value '{"color":"#ff0000"}'
+
+# Set a property from a JSON file
+confluence property-set 123456789 my-key --file ./property.json
+
+# Delete a property
+confluence property-delete 123456789 my-key
+
+# Skip confirmation on delete
+confluence property-delete 123456789 my-key --yes
+```
+
 ### Comments
 ```bash
 # List all comments (footer + inline)
@@ -296,6 +438,22 @@ confluence update 123456789 --file ./updated-content.md --format markdown
 confluence update 123456789 --title "New Title" --content "And new content"
 ```
 
+### Move a Page to New Parent
+
+```bash
+# Move page by ID
+confluence move 123456789 987654321
+
+# Move page and rename it
+confluence move 123456789 987654321 --title "Relocated Page"
+
+# Move using URLs (for convenience)
+confluence move "https://domain.atlassian.net/wiki/viewpage.action?pageId=123456789" \
+                "https://domain.atlassian.net/wiki/viewpage.action?pageId=987654321"
+```
+
+**Note:** Pages can only be moved within the same Confluence space. Cross-space moves are not supported.
+
 ### Delete a Page
 ```bash
 # Delete by page ID (prompts for confirmation)
@@ -321,6 +479,52 @@ vim ./page-to-edit.xml
 confluence update 123456789 --file ./page-to-edit.xml --format storage
 ```
 
+### Profile Management
+```bash
+# List all profiles and see which is active
+confluence profile list
+
+# Switch the active profile
+confluence profile use staging
+
+# Add a new profile interactively
+confluence profile add staging
+
+# Add a new profile non-interactively
+confluence profile add staging --domain "staging.example.com" --auth-type bearer --token "xyz"
+
+# Add a read-only profile (blocks all write operations)
+confluence profile add agent --domain "company.atlassian.net" --auth-type basic --email "bot@example.com" --token "xyz" --read-only
+
+# Remove a profile
+confluence profile remove staging
+
+# Use a specific profile for a single command
+confluence --profile staging spaces
+```
+
+### Read-Only Mode
+
+Read-only mode blocks all write operations at the CLI level, making it safe to hand the tool to AI agents (Claude Code, Copilot, etc.) without risking accidental edits.
+
+**Enable via profile:**
+```bash
+# During init
+confluence init --read-only
+
+# When adding a profile
+confluence profile add agent --domain "company.atlassian.net" --token "xyz" --read-only
+```
+
+**Enable via environment variable:**
+```bash
+export CONFLUENCE_READ_ONLY=true   # overrides profile setting
+```
+
+When read-only mode is active, any write command (`create`, `create-child`, `update`, `delete`, `move`, `edit`, `comment`, `attachment-upload`, `attachment-delete`, `property-set`, `property-delete`, `comment-delete`, `copy-tree`) exits with code 1 and prints an error message.
+
+`confluence profile list` shows a `[read-only]` badge next to protected profiles.
+
 ### View Usage Statistics
 ```bash
 confluence stats
@@ -330,7 +534,7 @@ confluence stats
 
 | Command | Description | Options |
 |---|---|---|
-| `init` | Initialize CLI configuration | |
+| `init` | Initialize CLI configuration | `--read-only` |
 | `read <pageId_or_url>` | Read page content | `--format <html\|text\|markdown>` |
 | `info <pageId_or_url>` | Get page information | |
 | `search <query>` | Search for pages | `--limit <number>` |
@@ -341,15 +545,28 @@ confluence stats
 | `create-child <title> <parentId>` | Create a child page | `--content <string>`, `--file <path>`, `--format <storage\|html\|markdown>` |
 | `copy-tree <sourcePageId> <targetParentId> [newTitle]` | Copy page tree with all children | `--max-depth <number>`, `--exclude <patterns>`, `--delay-ms <ms>`, `--copy-suffix <text>`, `--dry-run`, `--fail-on-error`, `--quiet` |
 | `update <pageId>` | Update a page's title or content | `--title <string>`, `--content <string>`, `--file <path>`, `--format <storage\|html\|markdown>` |
+| `move <pageId_or_url> <newParentId_or_url>` | Move a page to a new parent location | `--title <string>` |
 | `delete <pageId_or_url>` | Delete a page by ID or URL | `--yes` |
 | `edit <pageId>` | Export page content for editing | `--output <file>` |
 | `attachments <pageId_or_url>` | List or download attachments for a page | `--limit <number>`, `--pattern <glob>`, `--download`, `--dest <directory>` |
+| `attachment-upload <pageId_or_url>` | Upload attachments to a page | `--file <path>`, `--comment <text>`, `--replace`, `--minor-edit` |
+| `attachment-delete <pageId_or_url> <attachmentId>` | Delete an attachment from a page | `--yes` |
 | `comments <pageId_or_url>` | List comments for a page | `--format <text\|markdown\|json>`, `--limit <number>`, `--start <number>`, `--location <inline\|footer\|resolved>`, `--depth <root\|all>`, `--all` |
 | `comment <pageId_or_url>` | Create a comment on a page | `--content <string>`, `--file <path>`, `--format <storage\|html\|markdown>`, `--parent <commentId>`, `--location <inline\|footer>`, `--inline-selection <text>`, `--inline-original-selection <text>`, `--inline-marker-ref <ref>`, `--inline-properties <json>` |
 | `comment-delete <commentId>` | Delete a comment by ID | `--yes` |
+| `property-list <pageId_or_url>` | List all content properties for a page | `--format <text\|json>`, `--limit <number>`, `--start <number>`, `--all` |
+| `property-get <pageId_or_url> <key>` | Get a content property by key | `--format <text\|json>` |
+| `property-set <pageId_or_url> <key>` | Set a content property (create or update) | `--value <json>`, `--file <path>`, `--format <text\|json>` |
+| `property-delete <pageId_or_url> <key>` | Delete a content property by key | `--yes` |
 | `export <pageId_or_url>` | Export a page to a directory with its attachments | `--format <html\|text\|markdown>`, `--dest <directory>`, `--file <filename>`, `--attachments-dir <name>`, `--pattern <glob>`, `--referenced-only`, `--skip-attachments` |
+| `profile list` | List all configuration profiles | |
+| `profile use <name>` | Set the active configuration profile | |
+| `profile add <name>` | Add a new configuration profile | `-d, --domain`, `-p, --api-path`, `-a, --auth-type`, `-e, --email`, `-t, --token`, `--protocol`, `--read-only` |
+| `profile remove <name>` | Remove a configuration profile | |
 | `stats` | View your usage statistics | |
 
+**Global option:** `--profile <name>` — Use a specific profile for any command (overrides `CONFLUENCE_PROFILE` env var and active profile).
+
 ## Examples
 
 ```bash
@@ -371,15 +588,30 @@ confluence search "API documentation" --limit 3
 # List all spaces
 confluence spaces
 
+# Move a page to a new parent
+confluence move 123456789 987654321
+
+# Move and rename
+confluence move 123456789 987654321 --title "New Title"
+
+# Upload and delete an attachment
+confluence attachment-upload 123456789 --file ./report.pdf
+confluence attachment-delete 123456789 998877 --yes
+
 # View usage statistics
 confluence stats
+
+# Profile management
+confluence profile list
+confluence profile use staging
+confluence --profile staging spaces
 ```
 
 ## Development
 
 ```bash
 # Clone the repository
-git clone https://github.com/pchuri/confluence-cli.git
+git clone https://github.com/bestend/confluence-cli.git
 cd confluence-cli
 
 # Install dependencies
@@ -414,7 +646,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - [ ] Bulk operations
 - [ ] Export pages to different formats
 - [ ] Integration with other Atlassian tools (Jira)
-- [ ] Page attachments management
+- [x] Page attachments management (list, download, upload, delete)
 - [x] Comments
 - [ ] Reviews
 
@@ -425,15 +657,15 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 Your feedback helps make confluence-cli better for everyone. Here's how you can share your thoughts:
 
 #### 🐛 Found a bug?
-1. Check the [Issues](https://github.com/pchuri/confluence-cli/issues) page
-2. Create a new [bug report](https://github.com/pchuri/confluence-cli/issues/new?template=bug_report.md)
+1. Check the [Issues](https://github.com/bestend/confluence-cli/issues) page
+2. Create a new [bug report](https://github.com/bestend/confluence-cli/issues/new?template=bug_report.md)
 
 #### 💡 Have a feature idea?
-1. Create a [feature request](https://github.com/pchuri/confluence-cli/issues/new?template=feature_request.md)
-2. Join our [Discussions](https://github.com/pchuri/confluence-cli/discussions) to chat with the community
+1. Create a [feature request](https://github.com/bestend/confluence-cli/issues/new?template=feature_request.md)
+2. Join our [Discussions](https://github.com/bestend/confluence-cli/discussions) to chat with the community
 
 #### 📝 General feedback?
-- Share your experience with a [feedback issue](https://github.com/pchuri/confluence-cli/issues/new?template=feedback.md)
+- Share your experience with a [feedback issue](https://github.com/bestend/confluence-cli/issues/new?template=feedback.md)
 - Rate us on [NPM](https://www.npmjs.com/package/confluence-cli)
 - Star the repo if you find it useful! ⭐
 
@@ -442,12 +674,10 @@ Check out our [Contributing Guide](CONTRIBUTING.md) - all contributions are welc
 
 ### 📈 Usage Analytics
 
-To help us understand how confluence-cli is being used and improve it, we collect anonymous usage statistics. This includes:
-- Command usage frequency (no personal data)
-- Error patterns (to fix bugs faster)
-- Feature adoption metrics
+confluence-cli tracks command usage statistics **locally** on your machine (`~/.confluence-cli/stats.json`). No data is sent to any external server. This includes:
+- Command usage counts (success/error)
 
-You can opt-out anytime by setting: `export CONFLUENCE_CLI_ANALYTICS=false`
+You can view your stats with `confluence stats`, or disable tracking by setting: `export CONFLUENCE_CLI_ANALYTICS=false`
 
 ---