DokuWiki CLI Tools — PHP Commands, Maintenance Scripts, and the Indexer

In this tutorial, you'll learn how to manage DokuWiki from the command line using PHP scripts and CLI tools, including the indexer, cleanup scripts, user management, and automation.

What You'll Learn

• The bin/ directory and available CLI scripts
• Running the indexer manually
• User management from command line
• Cache and attic cleanup
• Plugin management from CLI
• Automation with Cron Jobs
• Writing custom CLI scripts

Why It Matters

The command line is faster than the web interface for bulk operations. Running the indexer from CLI is more reliable than triggering it via HTTP. Bulk user imports, cache cleanups, and attic purges are all easier from the terminal. For admins managing multiple wikis, CLI tools are essential for efficiency.

Real-World Use

A wiki admin runs a daily cron job that: purges attic files older than 90 days (keeping the 10 most recent revisions per page), rebuilds the search index, backs up the data/ directory, and sends a summary email. The entire maintenance pipeline runs from a bash script in under 2 minutes. No manual intervention needed.

Learning Path

flowchart LR
  A[Multi-Language] --> B[CLI Tools]
  B --> C[API]
  C --> D[Backup]
  D --> E[Upgrading]
  E --> F[Migration]

The bin/ Directory

DokuWiki includes several CLI scripts in the bin/ directory:

bin/
├── indexer.php      # Search index management
├── cleanup.php      # Revision and cache cleanup
├── wantedpages.php  # List non-existent linked pages
├── css.php          # CSS/LESS compilation
├── gittool.php      # Git integration
├── plugin.php       # Plugin management via CLI
├── rss.php          # RSS feed generation
└── striplangs.php   # Remove unused language files

Running CLI Scripts

# From the DokuWiki root directory
php bin/indexer.php
php bin/cleanup.php --help

The Indexer (bin/indexer.php)

The indexer manages the full-text search index.

Basic Usage

# Run the indexer (incremental update)
php bin/indexer.php

# Full re-index (rebuild entire index)
php bin/indexer.php -f

# Index a specific page
php bin/indexer.php -p projects:roadmap

# Index multiple pages
php bin/indexer.php -p "start projects:roadmap team:alice"

# Show indexing statistics
php bin/indexer.php -s

When to Rebuild

• After bulk importing pages
• If search returns incorrect results
• If index files are corrupted
• Monthly as preventive maintenance

Cache and Attic Cleanup (bin/cleanup.php)

The cleanup script manages disk space by purging old revisions and cache files.

Options

php bin/cleanup.php --help

--attic       Clean up old revisions (attic files)
--cache       Clean up rendering cache
--index       Clean up and rebuild index
--keep N      Keep N most recent revisions per page
--minage N    Keep revisions newer than N days
--dry-run     Show what would be done without doing it

Examples

# Show what old revisions would be removed
php bin/cleanup.php --attic --keep 5 --dry-run

# Keep 10 most recent revisions, purge older ones
php bin/cleanup.php --attic --keep 10

# Purge revisions older than 180 days
php bin/cleanup.php --attic --minage 180

# Full cleanup: revisions, cache, and index
php bin/cleanup.php --attic --keep 10
php bin/cleanup.php --cache
php bin/indexer.php -f

Plugin Management (bin/plugin.php)

# List installed plugins
php bin/plugin.php list

# Enable a plugin
php bin/plugin.php enable pluginname

# Disable a plugin
php bin/plugin.php disable pluginname

# Check for plugin updates
php bin/plugin.php checkupdates

User Management CLI

DokuWiki does not have a built-in CLI user management tool, but you can write one:

<?php
#!/usr/bin/php
// bin/adduser.php - Add a user from command line

if ($argc < 4) {
    echo "Usage: php adduser.php <username> <password> <fullname> <email> [groups]\n";
    exit(1);
}

$username = $argv[1];
$password = $argv[2];
$fullname = $argv[3];
$email = $argv[4];
$groups = $argv[5] ?? 'user';

// Generate bcrypt hash
$hash = password_hash($password, PASSWORD_BCRYPT);

// Append to users.auth.php
$line = implode(':', array($username, $hash, $fullname, $email, $groups)) . "\n";
file_put_contents('conf/users.auth.php', $line, FILE_APPEND);

echo "User '$username' added successfully.\n";

Usage:

php bin/adduser.php jdoe "securePass123" "John Doe" john@example.com "user,engineering"

Automation with Cron

Daily Maintenance Cron

# /etc/cron.d/dokuwiki-maintenance
# Run daily at 2 AM
0 2 * * * www-data cd /var/www/html/wiki && php bin/cleanup.php --attic --keep 10 --dry-run > /dev/null

# Run indexer daily at 3 AM
0 3 * * * www-data cd /var/www/html/wiki && php bin/indexer.php

# Backup data directory at 4 AM
0 4 * * * root tar -czf /backups/wiki-data-$(date +\%Y\%m\%d).tar.gz /var/www/html/wiki/data/

Cron Script Example

#!/bin/bash
# /usr/local/bin/wiki-maintenance.sh

WIKI_DIR="/var/www/html/wiki"
BACKUP_DIR="/var/www/backups"
DATE=$(date +%Y%m%d)

echo "[$DATE] Wiki maintenance starting..."

# Step 1: Clear old revisions (keep 10 most recent)
cd $WIKI_DIR
php bin/cleanup.php --attic --keep 10
echo "  Revisions cleaned."

# Step 2: Rebuild search index
php bin/indexer.php -f
echo "  Index rebuilt."

# Step 3: Backup data directory
tar -czf "$BACKUP_DIR/wiki-data-$DATE.tar.gz" data/
echo "  Backup created: $BACKUP_DIR/wiki-data-$DATE.tar.gz"

# Step 4: Clean backups older than 30 days
find $BACKUP_DIR -name "wiki-data-*.tar.gz" -mtime +30 -delete
echo "  Old backups removed."

echo "[$DATE] Maintenance complete."

Custom CLI Scripts

Page Export Script

<?php
#!/usr/bin/php
// bin/export-pages.php

require_once('inc/init.php');

$namespace = $argv[1] ?? '';
$outputDir = $argv[2] ?? 'export';

if (!is_dir($outputDir)) {
    mkdir($outputDir, 0755, true);
}

$pages = array();
search($pages, $conf['datadir'], 'search_allpages', array('ns' => $namespace));

foreach ($pages as $page) {
    $id = $page['id'];
    $content = rawWiki($id);
    $filename = str_replace(':', '/', $id) . '.txt';
    $filepath = $outputDir . '/' . $filename;

    $dir = dirname($filepath);
    if (!is_dir($dir)) {
        mkdir($dir, 0755, true);
    }

    file_put_contents($filepath, $content);
    echo "Exported: $id -> $filepath\n";
}

echo "Export complete. " . count($pages) . " pages exported.\n";

Bulk ACL Check Script

<?php
#!/usr/bin/php
// bin/check-acl.php

$username = $argv[1] ?? '';
if (!$username) {
    echo "Usage: php check-acl.php <username>\n";
    exit(1);
}

$pages = array();
search($pages, $conf['datadir'], 'search_allpages', array());

echo "ACL permissions for user: $username\n\n";
echo str_pad('Page ID', 40) . "Permission\n";
echo str_repeat('-', 55) . "\n";

foreach ($pages as $page) {
    $id = $page['id'];
    $perm = auth_quickaclcheck($id);
    echo str_pad($id, 40) . " " . $perm . "\n";
}

Common Mistakes

1. Running CLI scripts from the wrong directory: All CLI scripts must be run from the DokuWiki root directory. They depend on relative paths to include files.
2. Not running as the web server user: Scripts that modify files need the same permissions as the web server. Use sudo -u www-data php bin/indexer.php.
3. Forgetting the --dry-run flag on cleanup: The cleanup script permanently deletes files. Always use --dry-run first to preview the impact.
4. Skipping index rebuild after bulk imports: Pages imported via CLI are not automatically indexed. Always run php bin/indexer.php -f after bulk imports.
5. Ignoring PHP memory limits: Large wikis may need more memory for CLI scripts. Run with php -d memory_limit=512M bin/indexer.php -f.

Practice Questions

1. What CLI script would you use to rebuild the search index, and what flag forces a full rebuild?
2. How do you safely preview what the cleanup script will delete before running it?
3. Write a cron schedule that runs the indexer daily at 1 AM and purges attic files weekly on Sunday at 3 AM.
4. Challenge: Create a comprehensive maintenance script that: backs up the data/ directory with timestamp, purges attic files (keep 5 most recent), rebuilds the search index, generates a sitemap.xml, sends a summary email with backup size and page count, and logs all actions to a maintenance log file. The script should accept a --dry-run flag that shows what would be done without doing it. Test the script on a wiki installation.

FAQ

Mini Project

Goal: Set up automated CLI maintenance.

1. Explore the bin/ directory and list all available scripts
2. Run the indexer and observe the output
3. Run the cleanup script with --dry-run to see what would be purged
4. Write a maintenance script that: runs the cleanup (keep 10 revisions), rebuilds the index, exports a list of all pages to a CSV file, and logs to a maintenance log
5. Set up a cron job to run the script daily
6. Test that the cron job runs correctly
7. Verify the wiki works normally after automated maintenance

What's Next

CLI tools automate management. Now explore the API and integration options for connecting DokuWiki with external systems.