⚠️ Documentation Under Review: This documentation is currently being updated and verified against the actual implementation. Some information may be incorrect or incomplete. Please verify all code examples against the actual source code before use.
The Neuron CMS provides command-line utilities for installation, user management, and system administration. This reference documents only the commands that are actually registered and available.
./vendor/bin/neuron <command> [options] [arguments]
Install the CMS into your project.
Usage:
./vendor/bin/neuron cms:install
Description: Executes the interactive installation process, creating directories, publishing templates, configuring database, and creating the initial administrative user.
Interactive Prompts:
Options:
--force or -f: Force reinstall without prompts (overwrites existing files)--use-secrets or -s: Use encrypted credentials stored in secretsUpgrade the CMS to the latest version after running composer update.
Usage:
./vendor/bin/neuron cms:upgrade [options]
Description: Manages the CMS upgrade process by comparing installed and package versions, copying new migration files, updating configuration examples, and displaying version-specific upgrade notes. This command should be run after composer update neuron-php/cms.
Upgrade Process:
.cms-manifest.json) with package versiondb/migrate/.example files).cms-manifest.json with new version and migration listOptions:
--check: Check for available updates without applying them--migrations-only: Copy only new migration files, skip configuration updates--skip-views: Skip view template updates (preserves customizations)--run-migrations: Automatically execute database migrations after copying filesExamples:
# Standard upgrade workflow
composer update neuron-php/cms
./vendor/bin/neuron cms:upgrade
# Check for available updates
./vendor/bin/neuron cms:upgrade --check
# Upgrade and run migrations automatically
./vendor/bin/neuron cms:upgrade --run-migrations
# Copy only new migrations
./vendor/bin/neuron cms:upgrade --migrations-only
# Upgrade without updating views
./vendor/bin/neuron cms:upgrade --skip-views
Typical Workflow:
# 1. Enable maintenance mode
./vendor/bin/neuron cms:maintenance:enable "Upgrading system"
# 2. Backup database
mysqldump -u cms_user -p cms_database > backup.sql
# 3. Update package
composer update neuron-php/cms
# 4. Run upgrade command
./vendor/bin/neuron cms:upgrade
# 5. Apply database migrations
./vendor/bin/neuron db:migrate
# 6. Clear cache
./vendor/bin/neuron cache:clear
# 7. Disable maintenance mode
./vendor/bin/neuron cms:maintenance:disable
Output Example:
Neuron CMS Upgrade Utility
===========================
Current version: 0.8.5
Package version: 0.9.0
Upgrade available: 0.8.5 → 0.9.0
Checking for new migrations...
✓ Found 3 new migration files
Copying migrations:
✓ 20250205000000_add_timezone_to_users.php
✓ 20250206000000_create_pages_table.php
✓ 20250207000000_add_shortcode_to_pages.php
Updating configuration examples...
✓ config/neuron.yaml.example
✓ config/auth.yaml.example
Upgrade completed successfully!
=== UPGRADE NOTES FOR 0.9.0 ===
NEW FEATURES:
• Static pages support
• User timezone support
REQUIRED ACTIONS:
1. Run migrations: php neuron db:migrate
2. Update config/neuron.yaml with timezone settings
Next steps:
1. Review changes above
2. Run: php neuron db:migrate
3. Test your application
Related Documentation:
Create a new user account.
Usage:
./vendor/bin/neuron cms:user:create
Description: Interactive user creation with prompts for username, email, password, and role.
Interactive Prompts:
Options: None
List all users in the system.
Usage:
./vendor/bin/neuron cms:user:list
Description: Displays a formatted table of all users with ID, username, email, role, and status.
Options: None
Delete a user account.
Usage:
./vendor/bin/neuron cms:user:delete <identifier>
Arguments:
identifier: User ID or usernameDescription: Permanently deletes a user account. Prompts for confirmation.
Options: None
Examples:
# Delete by username
./vendor/bin/neuron cms:user:delete johndoe
# Delete by ID
./vendor/bin/neuron cms:user:delete 5
Reset a user's password.
Usage:
./vendor/bin/neuron cms:user:reset-password [options]
Description: Interactively reset a user's password. Identifies the user by username or email, validates password requirements, and clears any account lockouts. Useful for password recovery when users are locked out or have forgotten their credentials.
Options:
--username=<username> or -u: Specify username directly--email=<email> or -e: Specify email directlyInteractive Prompts:
Password Requirements:
Requirements are loaded from your site's password policy configuration (auth.passwords in config/auth.yaml):
Features:
Examples:
# Interactive mode - prompts for all inputs
./vendor/bin/neuron cms:user:reset-password
# Reset by username
./vendor/bin/neuron cms:user:reset-password --username=johndoe
# Reset by email
./vendor/bin/neuron cms:user:reset-password [email protected]
# Using short options
./vendor/bin/neuron cms:user:reset-password -u admin
./vendor/bin/neuron cms:user:reset-password -e [email protected]
Security Notes:
Common Use Cases:
# Admin locked out after too many failed attempts
./vendor/bin/neuron cms:user:reset-password -u admin
# User forgot password and can't access reset form
./vendor/bin/neuron cms:user:reset-password -e [email protected]
# Emergency password reset for compromised account
./vendor/bin/neuron cms:user:reset-password -u compromised_user
Enable maintenance mode.
Usage:
./vendor/bin/neuron cms:maintenance:enable [message]
Arguments:
message (optional): Maintenance message to display to usersDescription: Activates maintenance mode, displaying a maintenance page to users while allowing whitelisted IPs to access the system.
Options: None
Examples:
# Enable with default message
./vendor/bin/neuron cms:maintenance:enable
# Enable with custom message
./vendor/bin/neuron cms:maintenance:enable "Scheduled system updates"
Disable maintenance mode.
Usage:
./vendor/bin/neuron cms:maintenance:disable
Description: Deactivates maintenance mode, restoring normal system access.
Options: None
Check maintenance mode status.
Usage:
./vendor/bin/neuron cms:maintenance:status
Description: Displays current maintenance mode status, configured message, and allowed IP addresses.
Options: None
Install queue database tables.
Usage:
./vendor/bin/neuron queue:install
Description: Creates database tables required for queue operation when using database-based queue driver.
Options: None
Generate email template scaffold.
Usage:
./vendor/bin/neuron mail:generate <name>
Arguments:
name: Email template nameDescription: Creates a new email template file in resources/views/emails/.
Options: None
Example:
./vendor/bin/neuron mail:generate welcome
These commands manage encrypted configuration secrets using AES-256-CBC encryption.
Generate an encryption key for secrets.
Usage:
./vendor/bin/neuron secrets:key:generate [options]
Description: Creates a new 32-byte (64 hex characters) encryption key for encrypting secrets files. Keys are saved to config/master.key (base secrets) or config/environments/{env}.key (environment-specific secrets).
Options:
--env=<name>: Generate environment-specific key (e.g., local, production)--config=<path>: Configuration directory path (default: config)--show: Display the generated key in the terminal--force: Overwrite existing key file without confirmationExamples:
# Generate base master key
./vendor/bin/neuron secrets:key:generate
# Generate production environment key
./vendor/bin/neuron secrets:key:generate --env=production
# Generate and display key (for copying to environment variables)
./vendor/bin/neuron secrets:key:generate --show
# Force regenerate existing key
./vendor/bin/neuron secrets:key:generate --env=local --force
Security Notes:
.key files to version control - add to .gitignoreNEURON_MASTER_KEY or NEURON_{ENV}_KEY) instead of key filesRelated Files:
config/master.key - Base secrets encryption keyconfig/environments/{env}.key - Environment-specific encryption keysEdit encrypted secrets in your text editor.
Usage:
./vendor/bin/neuron secrets:edit [options]
Description: Opens encrypted secrets in your default text editor (defined by EDITOR environment variable or defaults to vi). The file is temporarily decrypted for editing, then automatically re-encrypted when you save and close the editor. Creates the secrets file and encryption key if they don't exist.
Options:
--env=<name>: Edit environment-specific secrets (e.g., local, production)--config=<path>: Configuration directory path (default: config)--editor=<command>: Use specific editor (e.g., nano, vim, code --wait)Examples:
# Edit base secrets
./vendor/bin/neuron secrets:edit
# Edit production environment secrets
./vendor/bin/neuron secrets:edit --env=production
# Edit with nano editor
./vendor/bin/neuron secrets:edit --editor=nano
# Edit local environment secrets with VS Code
./vendor/bin/neuron secrets:edit --env=local --editor=code --wait
Workflow:
Example Secrets File:
# These values are decrypted during editing
database:
password: my_secure_db_password
stripe:
api_key: sk_live_1234567890abcdef
webhook_secret: whsec_abcdefghijklmnop
smtp:
username: [email protected]
password: smtp_password_here
Security Notes:
/tmp/neuron_secrets_* filesRelated Files:
config/secrets.yml.enc - Encrypted base secretsconfig/environments/{env}.secrets.yml.enc - Encrypted environment secretsDisplay decrypted secrets.
Usage:
./vendor/bin/neuron secrets:show [options]
Description: Decrypts and displays secrets in the terminal. For production environment, requires confirmation to prevent accidental exposure of sensitive data.
Options:
--env=<name>: Show environment-specific secrets (e.g., local, production)--config=<path>: Configuration directory path (default: config)--key=<path>: Show only a specific key using dot notation (e.g., database.password)--force: Skip confirmation prompt for production secretsExamples:
# Show all base secrets
./vendor/bin/neuron secrets:show
# Show production secrets (requires confirmation)
./vendor/bin/neuron secrets:show --env=production
# Show specific key from local secrets
./vendor/bin/neuron secrets:show --env=local --key=database.password
# Show production Stripe API key
./vendor/bin/neuron secrets:show --env=production --key=stripe.api_key
# Skip confirmation (dangerous!)
./vendor/bin/neuron secrets:show --env=production --force
Output Example:
database:
password: my_secure_db_password
stripe:
api_key: sk_live_1234567890abcdef
webhook_secret: whsec_abcdefghijklmnop
smtp:
username: [email protected]
password: smtp_password_here
Security Notes:
--force is used--key option to display only specific values instead of all secretssecrets:edit for making changes rather than copying from secrets:showRelated Files:
config/secrets.yml.enc - Encrypted base secretsconfig/environments/{env}.secrets.yml.enc - Encrypted environment secretsCommon Use Cases:
# Verify database password for troubleshooting
./vendor/bin/neuron secrets:show --key=database.password
# Copy production API key to deployment platform
./vendor/bin/neuron secrets:show --env=production --key=stripe.api_key
# Inspect all local development secrets
./vendor/bin/neuron secrets:show --env=local
These commands are provided by the neuron-php/jobs component.
Run both scheduler and queue worker together.
Usage:
./vendor/bin/neuron jobs:run [options]
Description: Executes both the scheduler (for scheduled tasks) and queue worker (for asynchronous jobs) in a single process. This is the recommended way to run the complete job system.
Options:
--schedule-interval=<seconds>: Scheduler polling interval in seconds (default: 60)--queue=<names>: Comma-separated list of queue names to process (default: default)--worker-sleep=<seconds>: Sleep duration when queue is empty (default: 3)--worker-timeout=<seconds>: Job execution timeout in seconds (default: 60)--max-jobs=<count>: Maximum jobs to process before worker restart (default: unlimited)Examples:
# Run with defaults
./vendor/bin/neuron jobs:run
# Custom polling interval and specific queues
./vendor/bin/neuron jobs:run --schedule-interval=30 --queue=emails,notifications
# With worker configuration
./vendor/bin/neuron jobs:run --worker-sleep=5 --worker-timeout=120 --max-jobs=1000
Run the scheduler only.
Usage:
./vendor/bin/neuron jobs:schedule [options]
Description: Executes scheduled tasks defined in the schedule configuration without running the queue worker.
Options:
--interval=<seconds>: Polling interval in seconds (default: 60)--poll: Execute a single poll cycle and exit (useful for cron integration)Examples:
# Run continuously
./vendor/bin/neuron jobs:schedule
# Run once (for cron)
./vendor/bin/neuron jobs:schedule --poll
Run the queue worker only.
Usage:
./vendor/bin/neuron jobs:work [options]
Description: Processes queued jobs from the specified queue without running the scheduler.
Options:
--queue=<name>: Queue name to process (default: default)--sleep=<seconds>: Sleep duration when queue is empty (default: 3)--timeout=<seconds>: Job execution timeout in seconds (default: 60)--max-jobs=<count>: Maximum jobs to process before stoppingExamples:
# Process default queue
./vendor/bin/neuron jobs:work
# Process specific queue
./vendor/bin/neuron jobs:work --queue=emails
# Process with custom timeout and max jobs
./vendor/bin/neuron jobs:work --timeout=120 --max-jobs=100
List failed jobs.
Usage:
./vendor/bin/neuron jobs:failed
Description: Displays all failed jobs with their error information.
Options: None
Retry failed jobs.
Usage:
./vendor/bin/neuron jobs:retry <job-id>
Arguments:
job-id: ID of the failed job to retry, or "all" to retry all failed jobsDescription: Requeues failed jobs for processing.
Examples:
# Retry specific job
./vendor/bin/neuron jobs:retry 123
# Retry all failed jobs
./vendor/bin/neuron jobs:retry all
Flush failed jobs.
Usage:
./vendor/bin/neuron jobs:flush
Description: Removes all failed job records from the database.
Options: None
Forget a specific failed job.
Usage:
./vendor/bin/neuron jobs:forget <job-id>
Arguments:
job-id: ID of the failed job to forgetDescription: Removes a specific failed job record from the database.
Display job queue statistics.
Usage:
./vendor/bin/neuron jobs:stats
Description: Shows statistics about the job queue including pending, processing, failed, and completed job counts.
Options: None
These commands are provided by the neuron-php/mvc component for database schema management.
Create a new migration file.
Usage:
./vendor/bin/neuron db:migration:generate <name>
Arguments:
name: Migration name in PascalCaseOptions:
--class=<name>: Custom class name--template=<path>: Path to custom migration template--config=<path>: Path to configuration directoryExamples:
./vendor/bin/neuron db:migration:generate CreateUsersTable
./vendor/bin/neuron db:migration:generate AddEmailVerifiedToUsers
Execute pending database migrations.
Usage:
./vendor/bin/neuron db:migrate [options]
Options:
--target=<version>: Migrate to specific version--dry-run: Preview migrations without executing--fake: Mark migrations as run without executing--config=<path>: Path to configuration directoryExamples:
# Run all pending migrations
./vendor/bin/neuron db:migrate
# Migrate to specific version
./vendor/bin/neuron db:migrate --target=20250112143052
# Preview without executing
./vendor/bin/neuron db:migrate --dry-run
Rollback previously executed migrations.
Usage:
./vendor/bin/neuron db:rollback [options]
Options:
--target=<version>: Rollback to specific version--date=<date>: Rollback to specific date (YYYYMMDD)--force: Skip confirmation prompt--fake: Mark as rolled back without executing--config=<path>: Path to configuration directoryExamples:
# Rollback last migration
./vendor/bin/neuron db:rollback
# Rollback to specific version
./vendor/bin/neuron db:rollback --target=20250112143052
Display migration status.
Usage:
./vendor/bin/neuron db:migrate:status [options]
Options:
--format=<format>: Output format (text or json)--config=<path>: Path to configuration directoryDescription: Shows table of all migrations with ID, name, and status (up/down).
Execute database seeders.
Usage:
./vendor/bin/neuron db:seed [options]
Options:
--seed=<name> or -s: Specific seeder to run--config=<path>: Path to configuration directoryExamples:
# Run all seeders
./vendor/bin/neuron db:seed
# Run specific seeder
./vendor/bin/neuron db:seed --seed=UserSeeder
Export database schema to YAML format.
Usage:
./vendor/bin/neuron db:schema:dump [options]
Options:
--output=<path> or -o: Custom output file path--config=<path>: Path to configuration directoryDescription: Exports current database structure to YAML format for reference. The schema file includes:
Examples:
# Export to default location (db/schema.yaml)
./vendor/bin/neuron db:schema:dump
# Export to custom path
./vendor/bin/neuron db:schema:dump --output=docs/database-schema.yaml
Note: Schema file is for reference only. Always use migrations for actual database changes. Can be configured to auto-export after migrations by setting auto_dump_schema: true in configuration.
These commands are provided by the neuron-php/cli component.
Display help information.
Usage:
./vendor/bin/neuron help [command]
Arguments:
command (optional): Specific command to get help forDescription: Displays general help or help for a specific command.
Display version information.
Usage:
./vendor/bin/neuron version
Description: Shows the Neuron framework version and component versions.
List installed components.
Usage:
./vendor/bin/neuron component:list
Description: Displays all installed Neuron components with their versions.
All commands support the following global options:
--help, -h: Display command help--quiet, -q: Suppress output--verbose, -v: Increase output verbosity--version: Display version informationCommands follow standard exit code conventions:
0: Success1: General error2: Invalid arguments or usage