XWiki CLI

A modern command-line interface for managing XWiki instances via the REST API

XWiki CLI is a powerful command-line tool that allows you to interact with XWiki instances programmatically. It provides a clean, intuitive interface for common XWiki operations like managing spaces, pages, and performing full-text searches.

Features

• Space Management: List and browse wiki spaces
• Page Operations: Retrieve, list, and manage wiki pages
• Full-Text Search: Search across wiki content with filters
• Flexible Authentication: Support for username/password and environment variables
• Multiple Deployment Support: Automatically handles /rest and /xwiki/rest endpoint variations
• Type-Safe: Fully type-annotated with mypy strict mode
• Well-Tested: 93% code coverage with comprehensive test suite
• Modern Python: Built with Python 3.12+ and modern best practices

Table of Contents

• Installation
• Quick Start
• Configuration
• Usage
  • Listing Spaces
  • Getting Pages
  • Listing Pages
  • Searching
• CLI Reference
• Development
• Troubleshooting
• License

Installation

Prerequisites

• Python 3.12 or higher
• uv (recommended) or pip
• Access to an XWiki instance

Using uv (Recommended)

# Clone the repository
git clone https://github.com/jvanvinkenroye/xwiki-cli.git
cd xwiki-cli

# Create and activate virtual environment
uv venv --seed
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package
uv pip install -e .

Using pip

# Clone the repository
git clone https://github.com/jvanvinkenroye/xwiki-cli.git
cd xwiki-cli

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package
pip install -e .

Quick Start

# List all spaces in your wiki
python scripts/xwiki_cli.py \
  --base-url https://xwiki.example.org \
  --username alice \
  --password env:WIKI_PASS \
  spaces list

# Get a specific page
python scripts/xwiki_cli.py \
  --base-url https://xwiki.example.org \
  --username alice \
  --password env:WIKI_PASS \
  pages get --wiki xwiki --space Sandbox --page WebHome

# Search across the wiki
python scripts/xwiki_cli.py \
  --base-url https://xwiki.example.org \
  --username alice \
  --password env:WIKI_PASS \
  search --query "documentation" --limit 10

Configuration

Environment Variables

For security, it's recommended to store credentials in environment variables:

# Set your credentials
export XWIKI_USER="your-username"
export XWIKI_PASS="your-password"

# Use them in commands (credentials will be read automatically)
python scripts/xwiki_cli.py \
  --base-url https://xwiki.example.org \
  spaces list

Password Handling

The CLI supports multiple ways to provide passwords:

1. Environment variable reference (Recommended):

   export WIKI_PASSWORD="secret123"
   --password env:WIKI_PASSWORD
   

2. Direct environment variable:

   export XWIKI_PASS="secret123"
   # Password will be read from XWIKI_PASS automatically
   

3. Command line (Not recommended - visible in shell history):

   --password "secret123"
   

Base URL

The --base-url parameter should point to your XWiki instance:

• Include protocol: https://xwiki.example.org ✓
• Without trailing slash: https://xwiki.example.org ✓
• Avoid: https://xwiki.example.org/ ✗

The CLI automatically handles both /rest and /xwiki/rest endpoint patterns.

Usage

Listing Spaces

List all spaces in a wiki:

python scripts/xwiki_cli.py \
  --base-url https://xwiki.example.org \
  --username alice \
  --password env:WIKI_PASS \
  spaces list

List spaces in a different wiki:

python scripts/xwiki_cli.py \
  --base-url https://xwiki.example.org \
  --username alice \
  --password env:WIKI_PASS \
  spaces list --wiki otherwiki

Getting Pages

Retrieve a specific page:

python scripts/xwiki_cli.py \
  --base-url https://xwiki.example.org \
  --username alice \
  --password env:WIKI_PASS \
  pages get \
    --wiki xwiki \
    --space Sandbox \
    --page WebHome

The output is JSON containing page metadata and content:

{
  "id": "xwiki:Sandbox.WebHome",
  "title": "Sandbox Home",
  "name": "WebHome",
  "space": "Sandbox",
  "wiki": "xwiki",
  "version": "1.1",
  "author": "XWiki.Admin",
  "content": "..."
}

Listing Pages

List all pages in a space:

python scripts/xwiki_cli.py \
  --base-url https://xwiki.example.org \
  --username alice \
  --password env:WIKI_PASS \
  pages list \
    --wiki xwiki \
    --space Main

Searching

Full-text search across the wiki:

# Basic search
python scripts/xwiki_cli.py \
  --base-url https://xwiki.example.org \
  --username alice \
  --password env:WIKI_PASS \
  search \
    --query "documentation"

# Search with limit
python scripts/xwiki_cli.py \
  --base-url https://xwiki.example.org \
  --username alice \
  --password env:WIKI_PASS \
  search \
    --query "tutorial" \
    --limit 50

# Search within a specific space
python scripts/xwiki_cli.py \
  --base-url https://xwiki.example.org \
  --username alice \
  --password env:WIKI_PASS \
  search \
    --query "api" \
    --space "Dev" \
    --limit 20

CLI Reference

Global Options

All commands support these global options:

Option	Environment Variable	Description	Required
--base-url	-	XWiki instance URL	Yes
--username	XWIKI_USER	Username for authentication	No
--password	XWIKI_PASS	Password or env:VAR reference	No
--verbose	-	Enable debug logging	No
--quiet	-	Reduce log output	No

Commands

spaces list

List all spaces in a wiki.

Options:

• --wiki TEXT: Wiki identifier (default: xwiki)

Example:

python scripts/xwiki_cli.py --base-url URL spaces list --wiki xwiki

pages get

Retrieve a specific page.

Options:

• --wiki TEXT: Wiki identifier (default: xwiki)
• --space TEXT: Space name (required)
• --page TEXT: Page name (required)

Example:

python scripts/xwiki_cli.py --base-url URL pages get \
  --wiki xwiki --space Sandbox --page WebHome

pages list

List all pages in a space.

Options:

• --wiki TEXT: Wiki identifier (default: xwiki)
• --space TEXT: Space name (required)

Example:

python scripts/xwiki_cli.py --base-url URL pages list \
  --wiki xwiki --space Main

search

Full-text search across the wiki.

Options:

• --wiki TEXT: Wiki identifier (default: xwiki)
• --query TEXT: Search query (required)
• --space TEXT: Optional space filter
• --limit INTEGER: Maximum results (default: 20)

Example:

python scripts/xwiki_cli.py --base-url URL search \
  --query "documentation" --limit 10

Exit Codes

Code	Meaning
0	Success
1	General error (exception occurred)
2	HTTP error (API request failed)

Development

Setting Up Development Environment

# Clone the repository
git clone https://github.com/jvanvinkenroye/xwiki-cli.git
cd xwiki-cli

# Create virtual environment
uv venv --seed
source .venv/bin/activate

# Install development dependencies
uv pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Running Tests

# Run all tests
pytest

# Run with coverage report
pytest --cov=scripts --cov-report=html

# Run specific test file
pytest tests/test_client.py

# Run with verbose output
pytest -v

Code Quality Tools

The project uses several tools to maintain code quality:

# Lint and auto-fix issues
ruff check --fix .

# Format code
ruff format .

# Type check
mypy scripts/

# Run all pre-commit hooks
pre-commit run --all-files

Pre-commit Hooks

Pre-commit hooks run automatically on every commit:

• ruff: Linting with auto-fix
• ruff-format: Code formatting
• mypy: Type checking
• File checks: Large files, merge conflicts, YAML/TOML syntax
• Formatting: Trailing whitespace, line endings, EOF

Project Structure

xwiki-cli/
├── scripts/
│   └── xwiki_cli.py      # Main CLI implementation
├── tests/
│   ├── conftest.py       # Test fixtures
│   ├── test_client.py    # Client unit tests
│   └── test_cli.py       # CLI integration tests
├── .pre-commit-config.yaml  # Pre-commit hooks
├── pyproject.toml        # Project configuration
└── README.md            # This file

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and quality checks (pytest && pre-commit run --all-files)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Troubleshooting

Common Issues

Authentication Errors

Problem: HTTP 401 Unauthorized

Solutions:

• Verify your username and password are correct
• Ensure password environment variable is set correctly
• Check if your account has API access enabled in XWiki

Connection Errors

Problem: Connection refused or timeout errors

Solutions:

• Verify the base URL is correct and accessible
• Check if XWiki REST API is enabled
• Ensure you can access the URL in a browser
• Check firewall/proxy settings

REST Endpoint Not Found

Problem: No valid REST endpoint found

Solutions:

• The CLI automatically tries both /rest and /xwiki/rest patterns
• Verify your XWiki version supports the REST API
• Check XWiki logs for API-related errors
• Try accessing the REST API manually: https://your-wiki/rest/wikis

Empty Results

Problem: Commands return empty lists or no data

Solutions:

• Verify the wiki/space/page names are correct (case-sensitive)
• Check if your user has permission to view the content
• Try listing spaces first to verify connection: spaces list

Debug Mode

Enable verbose logging to see detailed information:

python scripts/xwiki_cli.py \
  --base-url https://xwiki.example.org \
  --verbose \
  spaces list

API Endpoint Variations

Different XWiki deployments may use different REST API base paths:

• Standard: https://xwiki.example.org/rest/
• Alternative: https://xwiki.example.org/xwiki/rest/

The CLI automatically detects and uses the correct endpoint.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with Click for CLI framework
• Uses requests for HTTP client
• Code quality with ruff and mypy
• Testing with pytest

---

Note: This is an unofficial tool and is not affiliated with or endorsed by the XWiki project.