Maintenance and Development Commands

Purpose and Scope

This section documents CLI commands used for system maintenance, development workflows, and administrative tasks. These commands facilitate managing maintenance mode, encryption key rotation, system health diagnostics, configuration management, and developer utilities like built-in servers, translation audits, layout debugging, and PayPal webhook testing.

For general CLI architecture and command discovery, see 10.1 CLI Architecture For cache and index management, see 10.3 Cache Management Commands and 10.4 Index Management Commands

---

Command Overview

Maintenance and Development Commands Architecture

Sources: lib/MahoCLI/Commands/HealthCheck.php22-26 lib/MahoCLI/Commands/CreateCommand.php22-26 lib/MahoCLI/Commands/TranslationsMissing.php24-28 lib/MahoCLI/Commands/LegacyRenameMysql4Classes.php21-25

---

Maintenance Mode Management

Overview

Maintenance mode prevents frontend access while allowing whitelisted IP addresses to continue accessing the site. This is critical during upgrades or migrations.

Commands

maintenance:enable, maintenance:disable, maintenance:status

These commands manage the presence of the maintenance.flag and maintenance.ip files in the root directory.

---

Encryption Key Management

sys:encryptionkey:regenerate

This command generates a new Sodium encryption key and re-encrypts sensitive data across the database. lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php24-28

Implementation Logic:

1. Validation: Before changing the key, the command performs a full validation pass via validateAllEncryptedData to ensure every existing encrypted value can be decrypted with the current key. lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php95-114
2. M1 Legacy Support: If an old Magento 1 key is detected (determined by key length), it checks for phpseclib/mcrypt_compat to perform the migration. lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php64-80
3. Transaction-Safe Re-encryption:
   • Re-encrypts admin_user table (specifically twofa_secret). lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php123
   • Re-encrypts core_config_data values where the configuration is marked as encrypted. lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php124
   • Dispatches encryption_key_regenerated event to allow external modules to update their data via provided callbacks. lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php126-130
4. Configuration Update: Updates <key> in app/etc/local.xml only after successful database re-encryption, creating a backup file named local.xml.bak.[date]. lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php144-150

Sources: lib/MahoCLI/Commands/SysEncryptionKeyRegenerate.php24-150 app/code/core/Mage/Core/Helper/Data.php65-78

---

Configuration Management

Maho provides direct CLI access to the core_config_data table, respecting scopes (default, website, store).

Commands

Command	Description
config:get	Retrieve a config value by path
config:set	Set a config value for a specific scope
config:delete	Remove a config entry

---

System Health and Diagnostics

health-check

Performs a suite of checks to ensure the Maho installation is healthy and follows modern standards. lib/MahoCLI/Commands/HealthCheck.php22-26

Key Checks:

• Composer Autoloader: Warns if an optimized autoloader is detected in development by checking the ClassLoader for Mage_Core_Model_App. lib/MahoCLI/Commands/HealthCheck.php108-116
• Legacy Core Files: Identifies old Magento/OpenMage files (e.g., app/Mage.php, app/code/core) that should be removed. lib/MahoCLI/Commands/HealthCheck.php28-32
• Deprecated Folders: Scans for legacy folders like lib/Zend or skin which are now managed differently in Maho. lib/MahoCLI/Commands/HealthCheck.php34-43
• Deprecated Classes: Detects usage of legacy Varien_ classes and suggests replacement with modern Maho\ equivalents (e.g., Varien_Object to Maho\DataObject). lib/MahoCLI/Commands/HealthCheck.php56-106
• Orphaned Resources: Checks for ACL resource IDs in the database that no longer exist in the system configuration via getOrphanedResourcesCollection. lib/MahoCLI/Commands/HealthCheck.php136-149

Sources: lib/MahoCLI/Commands/HealthCheck.php22-149

---

Localization and Translation Commands

dev:translations:missing and dev:translations:unused

These commands audit CSV files against the codebase to ensure complete and clean localization. lib/MahoCLI/Commands/TranslationsMissing.php24-28 lib/MahoCLI/Commands/TranslationsUnused.php25-29

Logic Flow for dev:translations:missing:

1. File Discovery: Scans the codebase for files calling the __() function or XML files with the translate attribute. lib/MahoCLI/Commands/TranslationsMissing.php79-88
2. String Extraction:
   • For PHP/PHTML: Uses regex to extract the first argument of __(). lib/MahoCLI/Commands/TranslationsMissing.php142-150
   • For XML: Uses XPath //*[@translate] to find nodes marked for translation and identifies children to translate. lib/MahoCLI/Commands/TranslationsMissing.php151-168
3. CSV Comparison: Loads existing translations from app/locale/[lang]/*.csv using Maho\File\Csv. lib/MahoCLI/Commands/TranslationsMissing.php95-112
4. Reporting: Identifies strings used in code but missing from the defined translation flat map. lib/MahoCLI/Commands/TranslationsMissing.php48-53

Logic Flow for dev:translations:unused:

• Identifies strings defined in CSV files that are no longer found in the codebase. lib/MahoCLI/Commands/TranslationsUnused.php52-55
• Cleanup: Includes a --remove option to automatically purge these lines from CSV files using removeUnusedFromFile. lib/MahoCLI/Commands/TranslationsUnused.php57-61 lib/MahoCLI/Commands/TranslationsUnused.php176-204

Sources: lib/MahoCLI/Commands/TranslationsMissing.php24-175 lib/MahoCLI/Commands/TranslationsUnused.php25-204 app/code/core/Mage/Core/Model/Translate.php13-116

---

Frontend Layout Debugging

dev:frontend:layout:debug

Provides visibility into how the layout for a specific URL is constructed, including handles and the resulting block tree.

Implementation Detail:

• Request Emulation: The command matches routers and dispatches the request internally to populate layout handles.
• Analysis:
  • Collects all layout handles via getHandles().
  • Identifies contributing XML files and theme inheritance chain.
  • Renders a tree of instantiated blocks.

---

PayPal Webhook Simulation

paypal:webhook:simulate

This command allows developers to test PayPal webhook handlers by simulating event payloads. lib/MahoCLI/Commands/PaypalWebhookSimulate.php21-25

Implementation:

• Interacts with the PayPal webhook processor to dispatch simulated JSON payloads to the appropriate handler.
• Useful for testing asynchronous payment status updates without requiring actual PayPal Sandbox interactions.

Sources: lib/MahoCLI/Commands/PaypalWebhookSimulate.php21-25

---

Developer Utilities

dev:create-command

An interactive utility to scaffold new Symfony-based CLI commands within the project. lib/MahoCLI/Commands/CreateCommand.php22-26

Implementation:

1. Input: Prompts for command name (e.g., cache:clean) and description. lib/MahoCLI/Commands/CreateCommand.php34-58
2. Class Generation: Converts the name to a CamelCase class name (e.g., CacheCleanCommand). lib/MahoCLI/Commands/CreateCommand.php105-108
3. File Creation: Generates a PHP file in ./lib/MahoCLI/Commands inheriting from BaseMahoCommand. lib/MahoCLI/Commands/CreateCommand.php110-150

Sources: lib/MahoCLI/Commands/CreateCommand.php22-150

dev:legacy:rename-mysql4-classes

A modernization utility that searches the codebase for legacy Mysql4 resource classes and replaces them with the modern Resource naming convention. lib/MahoCLI/Commands/LegacyRenameMysql4Classes.php21-25

Implementation:

• Maintains a comprehensive mapping of over 60 legacy class names (e.g., Mage_Admin_Model_Mysql4_Acl to Mage_Admin_Model_Resource_Acl). lib/MahoCLI/Commands/LegacyRenameMysql4Classes.php31-91
• Automates the refactoring of legacy class names to align with Maho's PSR-friendly resource model structure.

Sources: lib/MahoCLI/Commands/LegacyRenameMysql4Classes.php21-91

Maho Intelligence (LSP and MCP)

• dev:lsp:start: Starts the Language Server Protocol server, providing IDE features like code completion and diagnostics.
• dev:mcp:start: Starts the Model Context Protocol server for AI assistant integration.

serve and shell

• serve: Launches the built-in PHP development server targeting MAHO_PUBLIC_DIR (defaulting to 127.0.0.1:8000). lib/MahoCLI/Commands/Serve.php22-44
• shell: Provides an interactive PHP REPL (Read-Eval-Print Loop) with the Maho environment pre-initialized.

---

Base Command Infrastructure

All maintenance commands inherit from BaseMahoCommand, which provides essential bootstrap utilities.

Key Functionality:

• initMaho(): Initializes the Maho application in the admin store scope and sets isSecureArea to true to allow sensitive operations.
• humanReadableSize(): Utility for formatting byte sizes into kB, MB, GB, etc.

Sources: lib/MahoCLI/Commands/Serve.php22-45 app/bootstrap.php29-101