MODX CLI

A command-line interface for MODX 3, built with Symfony Console.

Requirements

• PHP 8.0 or higher
• MODX 3.0.0 or higher

Installation

Via Composer

composer global require finetuned/modx-cli

Manual Installation

1. Clone the repository:

git clone https://github.com/finetuned/modx-cli.git
cd modx-cli

2. Install dependencies:

composer install

3. Make the CLI executable:

chmod +x bin/modx

4. Create a symbolic link to make the CLI available globally:

sudo ln -s $(pwd)/bin/modx /usr/local/bin/modx

Usage

Basic Usage

modx [command] [options]

Available Commands

When a MODX instance is configured and set as default, many commands become available, including:

• version - Display the CLI version
• system:info - Get general system information
• system:clearcache - Clear the MODX cache
• resource:list - Get a list of resources
• resource:create - Create a MODX resource
• resource:update - Update a MODX resource (supports partial updates)
• chunk:list - Get a list of chunks
• chunk:create - Create a MODX chunk
• chunk:update - Update a MODX chunk (supports partial updates)
• template:list - Get a list of templates
• template:create - Create a MODX template
• template:update - Update a MODX template (supports partial updates)
• snippet:list - Get a list of snippets
• snippet:create - Create a MODX snippet
• snippet:update - Update a MODX snippet (supports partial updates)
• tv:list - Get a list of template variables
• tv:create - Create a MODX template variable
• tv:update - Update a MODX template variable (supports partial updates)
• user:list - Get a list of users
• package:list - Get a list of packages (supports pagination)
• crawl - Crawl resources to prime their caches
• And many more

To see all available commands, run:

modx list

Command Features

Update Commands: All update commands now support partial updates - you only need to specify the ID and the fields you want to change. The CLI automatically fetches existing data to populate required fields.

List Commands: All list commands support pagination with --limit and --start options for navigating large datasets.

JSON Output: All commands support --json flag for machine-readable output.

Enhanced Logging: Built-in PSR-3 compliant logging system with file logging, automatic rotation, and verbosity controls.

Logging

The CLI includes a comprehensive logging system for better debugging and operational visibility:

# Control console output verbosity
modx command -v          # verbose
modx command -vv         # very verbose
modx command -vvv        # debug
modx command --quiet     # no output

# Write logs to a file
modx command --log-file=/var/log/modx-cli.log

# Set log level (filters which messages are logged)
modx command --log-level=debug

All commands extending BaseCmd have automatic access to logging:

$this->logInfo('Processing started');
$this->logDebug('Item {id} processed', ['id' => 123]);
$this->logError('Operation failed: {error}', ['error' => $e->getMessage()]);

For complete documentation, see Enhanced Logging System.

Plugin Architecture

MODX CLI features a powerful plugin system for extending functionality without modifying core code:

// Create a plugin by extending AbstractPlugin
class MyPlugin extends AbstractPlugin
{
    public function getName(): string
    {
        return 'my-plugin';
    }

    public function getCommands(): array
    {
        return [MyCommand::class];
    }

    public function getHooks(): array
    {
        return [
            'command.before' => [$this, 'onCommandBefore']
        ];
    }
}

Features:

• Automatic plugin discovery and loading
• Hook system for event-driven extensions
• Command registration
• Configuration management
• Enable/disable functionality

For complete documentation, see Plugin Architecture.

Command Output Streaming

Enhanced output capabilities for long-running commands:

class MyCommand extends BaseCmd
{
    use StreamingOutputTrait;

    protected function process()
    {
        // Progress bars
        $this->startProgress(100, 'Processing...');
        $this->advanceProgress(10);
        $this->finishProgress();

        // Real-time streaming
        $this->stream('Processing item...');

        // Section-based output
        $section = $this->createSection();
        $section->write('Status: Running');
        $section->overwrite('Status: Complete');

        return 0;
    }
}

Features:

• Real-time streaming output
• Progress bars with custom formats
• Buffered and unbuffered modes
• Section-based output
• Event callbacks and statistics

For complete documentation, see Command Output Streaming.

Examples

Display the CLI version:

modx version

Get system information:

modx system:info

Clear the MODX cache:

modx system:clearcache

Get a list of resources:

modx resource:list

Get a list of resources with filters and pagination:

modx resource:list --parent=1 --context=web --published=1 --limit=20 --start=0

Update Command Examples

Update only the title of a resource (partial update):

modx resource:update 123 --pagetitle="New Title"

Update multiple fields of a chunk:

modx chunk:update 5 --description="Updated description" --snippet="<p>New content</p>"

Update a template variable with new default value:

modx tv:update 10 --default_text="New default value" --description="Updated TV"

Create Command Examples

Create a new resource with specific settings:

modx resource:create "My New Page" --parent=1 --template=2 --published=1

Create a new chunk:

modx chunk:create "MyChunk" --description="A new chunk" --snippet="<p>Chunk content</p>"

List Command Examples with Pagination

Get the first 10 packages:

modx package:list --limit=10 --start=0

Get the next 10 packages:

modx package:list --limit=10 --start=10

JSON Output Examples

Get resource data in JSON format:

modx resource:get 123 --json

Get a list of templates in JSON format:

modx template:list --json

Working with Multiple MODX Instances

Most commands in the MODX CLI require a MODX instance to be available. To see all available commands, you need to configure at least one MODX instance and set it as the default.

To add a MODX instance:

modx config:add mysite --base_path=/path/to/modx/

To set a MODX instance as the default:

modx config:set-default mysite

You can also specify a MODX instance to run a command on:

modx --site=mysite system:info

SSH and Aliases

MODX CLI supports running commands on remote servers via SSH and using aliases to simplify working with multiple MODX installations.

SSH Mode

Run commands on a remote server:

modx --ssh=user@example.com:/path/to/modx system:info

Aliases

Define aliases in ~/.modx/config.yml or modx-cli.yml in your project directory:

@prod:
  ssh: user@production-server.com:/path/to/modx
@staging:
  ssh: user@staging-server.com:/path/to/modx

Use aliases to run commands:

modx @prod system:info

Define alias groups to run commands on multiple servers:

@all:
  - @prod
  - @staging

modx @all system:clear-cache

For more information, see SSH and Aliases Documentation.

Documentation

User Guides

• Update Commands - Detailed guide to the enhanced update functionality
• List Commands - Pagination and filtering for list commands
• SSH and Aliases - Remote command execution and aliases
• Internal API - Programmatic usage and extending the CLI

Developer Guides

• Running Tests - Guide to running the test suite
• Debugging Setup - VS Code debugging configuration
• Code Style Guide - Coding standards and PHP_CodeSniffer setup
• Medium-Term Enhancements - Centralized error messages, field mappings, and metadata registry

Project Planning

• TODO Priority List - Prioritized list of technical debt items
• GitHub Issues to Create - Major initiative issue templates
• Type Declarations Progress - Tracking type hint implementation

Bash Completion

To enable bash completion, add the following to your .bashrc or .bash_profile:

source /path/to/modx_completion.sh

Building the PHAR

To build the PHAR file:

composer install --no-dev
box compile

This will create a modx-cli.phar file in the root directory.

Development

Code Quality

This project follows PSR-12 coding standards. Check your code style:

# Check code style
composer cs:check

# Automatically fix code style issues
composer cs:fix

Running Tests

# Run all tests
composer test

# Run unit tests only
composer test:unit

# Run integration tests only
composer test:integration

See Running Tests for more details.

Static Analysis

This project uses PHPStan for static analysis:

# Run static analysis
composer analyse

# Generate baseline for existing issues
composer analyse:baseline

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Before contributing, please:

1. Read the Code Style Guide
2. Ensure your code passes composer cs:check
3. Add tests for new functionality
4. Update documentation as needed

License

MIT