Metadata-Version: 2.4
Name: xwikiadmin
Version: 0.1.0
Summary: XWiki CLI - Command-line interface for managing XWiki instances via REST API
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: click>=8.3.1
Requires-Dist: requests>=2.32.5
Requires-Dist: requests-cache>=1.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
Requires-Dist: requests-mock>=1.11.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: types-requests>=2.31.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pre-commit>=3.6.0; extra == "dev"

# XWiki CLI

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

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![Code Coverage](https://img.shields.io/badge/coverage-93%25-brightgreen.svg)](https://github.com/jvanvinkenroye/xwiki-cli)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Type checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](http://mypy-lang.org/)

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](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Usage](#usage)
  - [Listing Spaces](#listing-spaces)
  - [Getting Pages](#getting-pages)
  - [Listing Pages](#listing-pages)
  - [Searching](#searching)
- [CLI Reference](#cli-reference)
- [Development](#development)
- [Troubleshooting](#troubleshooting)
- [License](#license)

## Installation

### Prerequisites

- Python 3.12 or higher
- [uv](https://github.com/astral-sh/uv) (recommended) or pip
- Access to an XWiki instance

### Using uv (Recommended)

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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):
   ```bash
   export WIKI_PASSWORD="secret123"
   --password env:WIKI_PASSWORD
   ```

2. **Direct environment variable**:
   ```bash
   export XWIKI_PASS="secret123"
   # Password will be read from XWIKI_PASS automatically
   ```

3. **Command line** (Not recommended - visible in shell history):
   ```bash
   --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:

```bash
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:

```bash
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:

```bash
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:

```json
{
  "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:

```bash
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:

```bash
# 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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
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](LICENSE) file for details.

## Acknowledgments

- Built with [Click](https://click.palletsprojects.com/) for CLI framework
- Uses [requests](https://requests.readthedocs.io/) for HTTP client
- Code quality with [ruff](https://github.com/astral-sh/ruff) and [mypy](http://mypy-lang.org/)
- Testing with [pytest](https://pytest.org/)

---

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