acon

command module

v1.5.0 Latest Latest Go to latest Published: Feb 3, 2026 License: MPL-2.0 Imports: 1 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/grantcarthew/acon

Links

Open Source Insights

README ¶

acon

A fast, simple command-line tool for Atlassian Confluence - because the web editor is not it.

Manage Confluence pages and spaces from your terminal with full Markdown support. Create, edit, and publish documentation without ever opening a browser.

# Write documentation in Markdown, publish to Confluence
echo "# API Docs\n\nYour content here" | acon page create -t "API Documentation"

# Edit pages with your favorite editor
acon page view 123456 > docs.md
vim docs.md
acon page update 123456 -f docs.md

Features

Bidirectional Markdown conversion - Write in Markdown, view in Markdown, never touch HTML
Full page management - Create, view, update, delete, and list pages
Powerful search - CQL-based search with simple flags for common queries
Space operations - View and list Confluence spaces
JSON output - Perfect for scripting and automation
Environment-based config - No config files, works with existing Atlassian tokens
Shell completion - Bash, Zsh, and Fish support

Quick Start

Installation

Homebrew (macOS/Linux):

# Add the tap first
brew tap grantcarthew/tap

# Then install
brew install acon

# Or do it in one command
brew install grantcarthew/tap/acon

Check out my other Homebrew packages in the tap!

Go install:

go install github.com/grantcarthew/acon@latest

From source:

git clone https://github.com/grantcarthew/acon.git
cd acon
go build -o acon
sudo mv acon /usr/local/bin/

Configuration

Set the following environment variables:

export CONFLUENCE_BASE_URL="https://your-instance.atlassian.net"
export CONFLUENCE_EMAIL="your-email@example.com"
export CONFLUENCE_API_TOKEN="your-api-token"
export CONFLUENCE_SPACE_KEY="YOUR_SPACE"  # (Optional)

Get an API token at: https://id.atlassian.com/manage-profile/security/api-tokens

Note: The same API token works for Confluence and Jira. You can use CONFLUENCE_API_TOKEN, ATLASSIAN_API_TOKEN, or JIRA_API_TOKEN.

First Commands

# List spaces you have access to
acon space list

# List pages in a space
acon page list -s MYSPACE

# Create a page from Markdown
cat README.md | acon page create -t "My Documentation"

# View a page (outputs Markdown)
acon page view 123456789

Usage

Commands Overview

acon [command]

Available Commands:
  page        Manage Confluence pages
  space       Manage Confluence spaces
  search      Search Confluence content
  debug       Debug converter functions
  completion  Generate shell completion
  help        Help about any command

Flags:
  -h, --help      help for acon
  -v, --version   Print version

Page Commands

`acon page create`

Create a new Confluence page from Markdown.

acon page create -t TITLE [flags]

Flags:
  -f, --file string     Markdown file to read (default: stdin)
  -j, --json           Output JSON instead of human-readable format
  -m, --message string Version message
  -p, --parent string  Parent page ID
  -s, --space string   Space key (uses CONFLUENCE_SPACE_KEY if not set)
  -t, --title string   Page title (required)

Examples:

# Create from file
acon page create -t "API Documentation" -f api-docs.md

# Create from stdin
echo "# Hello World" | acon page create -t "Hello"

# Create in specific space with parent
acon page create -t "Child Page" -f content.md -s MYSPACE -p 123456

# JSON output for scripting
acon page create -t "Title" -f content.md -j

`acon page view`

View a Confluence page (outputs Markdown).

acon page view PAGE_ID [flags]

Arguments:
  PAGE_ID   Confluence page ID (required)

Flags:
  -j, --json   Output JSON instead of Markdown

Examples:

# View as Markdown
acon page view 123456789

# View as JSON
acon page view 123456789 -j

# Save to file
acon page view 123456789 > local-copy.md

# Edit and update workflow
acon page view 123456789 > docs.md
vim docs.md
acon page update 123456789 -f docs.md

`acon page update`

Update an existing Confluence page.

acon page update PAGE_ID [flags]

Arguments:
  PAGE_ID   Confluence page ID (required)

Flags:
  -f, --file string     Markdown file to read (default: stdin)
  -j, --json           Output JSON instead of human-readable format
  -m, --message string Version message (appears in page history)
  -t, --title string   New page title (optional, keeps existing if not set)

Examples:

# Update content from file
acon page update 123456789 -f updated-docs.md

# Update content from stdin
cat updated-docs.md | acon page update 123456789

# Update title and content
acon page update 123456789 -t "New Title" -f updated-docs.md

# Add version message
acon page update 123456789 -f docs.md -m "Updated API endpoints"

`acon page delete`

Delete a Confluence page.

acon page delete PAGE_ID

Arguments:
  PAGE_ID   Confluence page ID (required)

Example:

acon page delete 123456789

`acon page move`

Move a Confluence page to a new parent within the same space.

acon page move PAGE_ID [flags]

Arguments:
  PAGE_ID   Confluence page ID (required)

Flags:
  -j, --json            Output JSON instead of human-readable format
  -p, --parent string   Target parent page ID (required)

Examples:

# Move a page under a new parent
acon page move 123456789 --parent 987654321

# JSON output
acon page move 123456789 --parent 987654321 -j

Note: Cross-space moves are not supported by the Confluence API. To move a page to a different space, create the page in the new space and delete the original.

`acon page list`

List pages in a Confluence space or children of a specific page.

acon page list [flags]

Flags:
      --desc            Sort in descending order
  -j, --json            Output JSON instead of human-readable format
  -l, --limit int       Maximum number of pages to return (default: 25)
  -p, --parent string   Parent page ID (list children of this page)
      --sort string     Sort order (see below)
  -s, --space string    Space key (uses CONFLUENCE_SPACE_KEY if not set)

Sort options:

With --parent: web (default), title, created, modified, id
Without --parent: title, created, modified, id

The web sort matches the manual page order in Confluence's web interface.

Examples:

# List pages in default space
acon page list

# List pages in specific space
acon page list -s MYSPACE

# List child pages of a parent
acon page list --parent 123456789

# Sort by creation date (newest first)
acon page list --parent 123456789 --sort created --desc

# Sort by title
acon page list -s MYSPACE --sort title

# Reverse default order
acon page list --parent 123456789 --desc

# Limit results
acon page list -l 10

# JSON output
acon page list -j

Search Commands

`acon search`

Search Confluence content using CQL (Confluence Query Language).

acon search [QUERY] [flags]

Arguments:
  QUERY   Optional positional text query for full-text search

Flags:
      --cql string       Raw CQL query (overrides all other flags)
      --creator string   Filter by creator (email or 'me')
  -j, --json            Output JSON instead of human-readable format
      --label string     Search by label (exact match)
  -l, --limit int       Maximum number of results (default: 25)
  -s, --space string    Filter by space key (uses CONFLUENCE_SPACE_KEY if not set)
      --title string     Search in page titles
      --type string      Content type (page, blogpost, attachment, etc.)

How Search Works:

By default, searches pages only (type=page)
All search criteria are combined with AND logic
The positional QUERY argument searches across titles, bodies, and labels
Use --cql for advanced queries (date ranges, OR logic, ancestor searches)

Examples:

# Simple full-text search
acon search "api documentation"

# Search with space filter
acon search "meeting notes" -s DEV

# Title-only search
acon search --title "Security Review"

# Multiple filters
acon search "api" --label important --creator me -s DEV

# Label-only search
acon search --label urgent

# Creator filter (use 'me' for current user)
acon search --creator me --label todo
acon search "refactor" --creator user@example.com

# Search different content types
acon search "diagram" --type attachment -s TEAM

# Limit results
acon search "bug" -l 10

# JSON output for scripting
acon search "api" -s DEV -j

# Advanced CQL for complex queries
acon search --cql "type=page and ancestor=123456 and created>=startOfDay('-7d')"
acon search --cql "type=page and (label=urgent or label=critical)"

Output Format:

Page Title (SPACE_KEY)
https://your-instance.atlassian.net/wiki/spaces/SPACE/pages/123456/Page+Title
...excerpt with matching text...
Modified: 2024-01-15

---
Showing 25 of 150 results

Tips:

Use quotes around multi-word queries: "api docs"
The me alias automatically resolves to your user: --creator me
Combine flags for precise searches: text + title + label + space
Use --cql for advanced features not available via simple flags
CQL reference: Confluence Query Language

Space Commands

`acon space view`

View details about a Confluence space.

acon space view SPACE_KEY [flags]

Arguments:
  SPACE_KEY   Confluence space key (required)

Flags:
  -j, --json   Output JSON instead of human-readable format

Examples:

# View space details
acon space view MYSPACE

# JSON output
acon space view MYSPACE -j

`acon space list`

List Confluence spaces you have access to.

acon space list [flags]

Flags:
  -j, --json       Output JSON instead of human-readable format
  -l, --limit int  Maximum number of spaces to return (default: 25)

Examples:

# List all accessible spaces
acon space list

# Limit results
acon space list -l 10

# JSON output for scripting
acon space list -j

Debug Commands

Debug commands help troubleshoot Markdown conversion issues.

`acon debug md`

Convert Markdown to Confluence storage format (for debugging).

echo "# Test" | acon debug md
cat document.md | acon debug md

`acon debug storage`

Convert Confluence storage format to Markdown (for debugging).

echo "<h1>Test</h1>" | acon debug storage
cat storage.xml | acon debug storage

Shell Completion

Generate shell completion scripts for Bash, Zsh, or Fish.

acon completion [bash|zsh|fish]

Installation:

# Bash (add to ~/.bashrc or /etc/bash_completion.d/)
acon completion bash > /usr/local/etc/bash_completion.d/acon

# Zsh (add to ~/.zshrc or fpath)
acon completion zsh > "${fpath[1]}/_acon"

# Fish
acon completion fish > ~/.config/fish/completions/acon.fish

Markdown Support

acon provides seamless bidirectional Markdown conversion:

When Creating/Updating Pages (Markdown → Confluence)

Your Markdown is automatically converted to Confluence storage format:

Markdown	Result
`# Heading 1`	Heading 1
`## Heading 2`	Heading 2
`bold`	Bold text
`italic`	Italic text
`code`	Inline code
```language	Code block
`[text](url)`	Hyperlink
`- item` or `* item`	Unordered list
`1. item`	Ordered list
`> quote`	Blockquote

When Viewing Pages (Confluence → Markdown)

Confluence storage format is converted back to clean, readable Markdown - perfect for editing locally.

Supported conversions:

Tables
Nested lists
Code blocks with syntax highlighting
Links (internal and external)
Strikethrough
All CommonMark features

Feature Support Details

For a complete feature support matrix, known limitations, and Confluence-specific quirks, see the testdata/README.md documentation.

Examples

Create Documentation from Local Files

# Single file
acon page create -t "Installation Guide" -f docs/install.md

# Batch create multiple pages
for file in docs/*.md; do
  title=$(basename "$file" .md)
  acon page create -t "$title" -f "$file" -s DOCS
done

Edit-Update Workflow

# Download page to local file
acon page view 123456789 > docs.md

# Edit with your favourite editor
vim docs.md
# or code docs.md
# or emacs docs.md

# Upload changes
acon page update 123456789 -f docs.md -m "Updated via acon"

Scripting with JSON Output

# Get page ID by title (requires jq)
PAGE_ID=$(acon page list -j | jq -r '.results[] | select(.title=="My Page") | .id')

# Bulk operations
acon space list -j | jq -r '.results[].key' | while read space; do
  echo "Pages in $space:"
  acon page list -s "$space" -l 5
done

CI/CD Integration

# Deploy docs to Confluence from GitHub Actions
name: Deploy Docs
on:
  push:
    branches: [main]
    paths: [docs/**]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.23'
      - run: go install github.com/grantcarthew/acon@latest
      - name: Update Confluence
        env:
          CONFLUENCE_BASE_URL: ${{ secrets.CONFLUENCE_BASE_URL }}
          CONFLUENCE_EMAIL: ${{ secrets.CONFLUENCE_EMAIL }}
          CONFLUENCE_API_TOKEN: ${{ secrets.CONFLUENCE_API_TOKEN }}
        run: |
          acon page update ${{ vars.DOCS_PAGE_ID }} -f docs/README.md -m "Deploy from ${{ github.sha }}"

Backup Confluence Pages

#!/bin/bash
# backup-confluence.sh - Backup all pages in a space

SPACE="MYSPACE"
BACKUP_DIR="confluence-backup-$(date +%Y%m%d)"

mkdir -p "$BACKUP_DIR"

# Get all page IDs
PAGE_IDS=$(acon page list -s "$SPACE" -j | jq -r '.results[].id')

# Download each page
for id in $PAGE_IDS; do
  title=$(acon page view "$id" -j | jq -r '.title' | tr ' ' '-')
  echo "Backing up: $title"
  acon page view "$id" > "$BACKUP_DIR/${id}-${title}.md"
done

echo "Backup complete: $BACKUP_DIR"

Environment Variables

Variable	Required	Description	Example
`CONFLUENCE_BASE_URL`	Yes	Your Confluence instance URL	`https://company.atlassian.net`
`CONFLUENCE_EMAIL`	Yes	Your email address	`user@example.com`
`CONFLUENCE_API_TOKEN`	Yes*	Atlassian API token	Get from API tokens
`ATLASSIAN_API_TOKEN`	Yes*	Alternative to CONFLUENCE_API_TOKEN	Same token works for all Atlassian products
`JIRA_API_TOKEN`	Yes*	Alternative (if you already have Jira token)	Same token works for Confluence
`CONFLUENCE_SPACE_KEY`	No	Default space key (avoids `-s` flag)	`DOCS`, `TEAM`, etc.

Note: Only one API token variable is required. acon checks in order: CONFLUENCE_API_TOKEN → ATLASSIAN_API_TOKEN → JIRA_API_TOKEN.

Development

Building from Source

git clone https://github.com/grantcarthew/acon.git
cd acon
go mod download
go build -o acon

Project Structure

acon/
├── cmd/                    # Cobra CLI commands
│   ├── root.go            # Root command and version
│   ├── page.go            # Page subcommands
│   ├── space.go           # Space subcommands
│   └── debug.go           # Debug subcommands
├── internal/
│   ├── api/               # Confluence REST API client
│   │   └── client.go
│   ├── config/            # Environment variable loader
│   │   └── config.go
│   └── converter/         # Bidirectional Markdown conversion
│       ├── markdown.go    # Markdown → Confluence storage
│       └── storage.go     # Confluence storage → Markdown
├── docs/                  # Documentation and processes
│   └── tasks/
│       ├── code-review.md
│       └── release-process.md
├── testdata/              # Test fixtures and feature documentation
│   ├── comprehensive-test.md  # Full Markdown feature test
│   ├── roundtrip-test.sh      # Automated round-trip testing
│   └── README.md          # Feature support matrix and known gaps
├── main.go                # Entry point
├── AGENTS.md              # Agent development guidelines
└── README.md

Dependencies

cobra - CLI framework
html-to-Markdown - Confluence storage to Markdown converter

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Run gofmt -w . before committing
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

See AGENTS.md for detailed development guidelines.

Troubleshooting

"API token not set" Error

Ensure one of these environment variables is set:

CONFLUENCE_API_TOKEN
ATLASSIAN_API_TOKEN
JIRA_API_TOKEN

# Check if set
echo $CONFLUENCE_API_TOKEN

# Set it
export CONFLUENCE_API_TOKEN="your-token-here"

"space not found" Error

Verify the space exists and you have access:

# List all spaces you can access
acon space list

# Try viewing the specific space
acon space view YOUR_SPACE_KEY

HTTP 401 Unauthorized

Verify your email is correct
Check if API token is valid (they don't expire but can be revoked)
Ensure you're using the correct Confluence instance URL
Create a new API token if needed

HTTP 404 Not Found

Verify page ID or space key is correct
Check if the page/space still exists (might have been deleted)
Ensure you have permission to access the resource

Build Errors

# Clean and rebuild
go clean -modcache
go mod download
go mod verify
go build -o acon

FAQ

Q: Can I use this with Confluence Server/Data Center?

A: Currently acon targets Confluence Cloud (REST API v2). Server/Data Center support could be added - PRs welcome!

Q: Does this support attachments?

A: Not yet. File attachment support is planned for a future release.

Q: Can I migrate content from other systems?

A: Yes! If you can convert your content to Markdown, acon can publish it to Confluence. Great for migrating from GitHub wikis, GitBook, MkDocs, etc.

Q: Is there a way to search pages?

A: Yes! Use acon search with simple flags or advanced CQL queries. See the Search Commands section for examples.

Q: Can I use this in CI/CD?

A: Absolutely! See the CI/CD Integration example above.

jira-cli - CLI for Jira (pairs great with acon)
pandoc - Universal document converter
glab - GitLab CLI

License

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.

See LICENSE for full details.

Author

Grant Carthew - GitHub

Made with ❤️ for everyone who hates editing docs in a web browser.

Star this repo if acon makes your documentation workflow better!

Documentation ¶

There is no documentation for this package.

Source Files ¶

View all Source files

main.go

Directories ¶

Path	Synopsis
cmd
internal
api
config
converter

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

README ¶

acon

Features

Quick Start

Installation

Configuration

First Commands

Usage

Commands Overview

Page Commands

acon page create

acon page view

acon page update

acon page delete

acon page move

acon page list

Search Commands

acon search

Space Commands

acon space view

acon space list

Debug Commands

acon debug md

acon debug storage

Shell Completion

Markdown Support

When Creating/Updating Pages (Markdown → Confluence)

When Viewing Pages (Confluence → Markdown)

Feature Support Details

Examples

Create Documentation from Local Files

Edit-Update Workflow

Scripting with JSON Output

CI/CD Integration

Backup Confluence Pages

Environment Variables

Development

Building from Source

Project Structure

Dependencies

Contributing

Troubleshooting

"API token not set" Error

"space not found" Error

HTTP 401 Unauthorized

HTTP 404 Not Found

Build Errors

FAQ

Related Projects

License

Author

Documentation ¶

Source Files ¶

Directories ¶

`acon page create`

`acon page view`

`acon page update`

`acon page delete`

`acon page move`

`acon page list`

`acon search`

`acon space view`

`acon space list`

`acon debug md`

`acon debug storage`