PHPackages                             atomicsmash/nucleus-cli - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [CLI & Console](/categories/cli)
4. /
5. atomicsmash/nucleus-cli

ActiveComposer-plugin[CLI & Console](/categories/cli)

atomicsmash/nucleus-cli
=======================

Development CLI toolkit for onboarding and managing WordPress projects

00[7 issues](https://github.com/AtomicSmash/nucleus-cli/issues)PHP

Since Jul 6Pushed todayCompare

[ Source](https://github.com/AtomicSmash/nucleus-cli)[ Packagist](https://packagist.org/packages/atomicsmash/nucleus-cli)[ RSS](/packages/atomicsmash-nucleus-cli/feed)WikiDiscussions main Synced today

READMEChangelog (1)DependenciesVersions (3)Used By (0)

Nucleus CLI
===========

[](#nucleus-cli)

A WordPress development toolkit for working with projects that use composer and node to manage assets with a DevOps focus.

Installation
------------

[](#installation)

You can install the package globally via composer:

```
composer global require atomicsmash/nucleus-cli
```

Usage
-----

[](#usage)

Nucleus provides several commands to help set up and manage WordPress projects:

### Full Project Setup

[](#full-project-setup)

Run a complete project setup that executes all setup commands in sequence:

```
nucleus project:setup
```

This command will:

1. Ask for confirmation to proceed with the overall setup
2. For each setup command, show a description and ask if you want to run it:
    - **Project Configuration**: Collect and store project settings (vendor, project name, web root, etc.)
    - **Project Core Setup**: Copy and configure core project files (composer.json, wp-config.php, etc.)
    - **WordPress Setup**: Move WordPress to the correct location and organise wp-content directory
    - **Plugin Migration**: Migrate WordPress plugins to Composer via wpackagist
    - **Theme Cleanup**: Remove unused themes, keeping only the active theme and its parent
3. Allow you to skip any individual section if you don't need it
4. Provide a summary of completed tasks and next steps

You can also run each command independently if you prefer to set up your project step by step.

### Project Configuration

[](#project-configuration)

Configure project settings that are shared across all commands:

```
nucleus project:config
```

This command collects and stores the following project information:

- **Basic Project Settings**: Vendor name, project name, description, license, slug
- **WordPress Configuration**: Web root path, WordPress install path, PHP version
- **Theme Selection**: Choose from available themes in current WordPress installation
- **Git Configuration**: Remote SSH URL, default branch

The configuration is stored in memory and used by subsequent commands, eliminating duplicate prompts.

### WordPress Setup

[](#wordpress-setup)

Set up your WordPress installation with proper directory structure:

```
nucleus wordpress:setup
```

**Note**: Requires project configuration to be set up first using `nucleus project:config`.

The command will:

1. Use stored project configuration (web root, WordPress install path)
2. Find your WordPress installation in common locations
3. Move WordPress to the specified location within the web root
4. Move the `wp-content` directory to the web root
5. Remove WordPress core files from the target location
6. Provide next steps guidance

### WordPress User Management

[](#wordpress-user-management)

Manage WordPress users across development, staging, and production environments:

```
nucleus wordpress:user add
nucleus wordpress:user list
nucleus wordpress:user delete
```

**Requirements:**

- A `wp-cli.yml` file in the project root (marks the project as a WordPress installation)
- WP-CLI installed locally for development commands
- A `.env` file with SSH credentials for staging and production

**Environment selection:** Each command prompts you to choose an environment (defaults to **development**). For staging and production, WP-CLI commands are run remotely over SSH using credentials from your `.env` file.

**Required `.env` variables for remote environments:**

VariableDescription`STAGING_SSH_HOST`Staging server hostname`STAGING_SSH_USER`Staging SSH username`STAGING_SSH_PORT`Staging SSH port`STAGING_WEB_ROOT`Absolute path to WordPress on staging`PRODUCTION_SSH_HOST`Production server hostname`PRODUCTION_SSH_USER`Production SSH username`PRODUCTION_SSH_PORT`Production SSH port`PRODUCTION_WEB_ROOT`Absolute path to WordPress on production**Optional `.env` defaults for `wordpress:user add`:**

VariableDescription`WORDPRESS_USER`Default username`WORDPRESS_USER_EMAIL`Default email address`WORDPRESS_PASSWORD`Default password### Project Core Setup

[](#project-core-setup)

Copy and configure core project files from templates:

```
nucleus project:core
```

**Note**: Requires project configuration to be set up first using `nucleus project:config`.

The command will:

1. Use stored project configuration (vendor, project name, web root, etc.)
2. Collect environment-specific configuration (database settings, security keys, external services)
3. Copy template files from the nucleus package:
    - `.config/wp-configs/*` → `.config/wp-configs/`
    - `public/wp-config.php` → `[web-root]/wp-config.php`
    - `.editorconfig` → `.editorconfig`
    - `.gitignore` → `.gitignore`
    - `.valetrc` → `.valetrc`
    - `composer.json` → `composer.json`
    - `herd.yml` → `herd.yml`
4. Replace placeholders with collected configuration
5. Handle file conflicts with options to overwrite, backup and replace, or skip

### Plugin Migration

[](#plugin-migration)

Migrate your WordPress plugins to Composer via wpackagist:

```
nucleus plugins:migrate
```

The command will:

1. Look for the `wp-content` directory in either:
    - The project root
    - A `public` directory
2. If not found, prompt you to enter the path or quit
3. Scan all plugins in the plugins directory
4. For each plugin:
    - Extract its version from the main plugin file
    - Check if it exists in the WordPress plugin directory
    - If it exists, add it to composer via wpackagist
    - If not, add it to a list of not found plugins
5. Display any plugins that weren't found in the WordPress directory

### Plugins Update

[](#plugins-update)

Run the monthly plugin update workflow with optional maintenance emails and deploy steps:

```
nucleus plugins:update
```

**Requirements:** Project must have `composer.json` with `johnpbloch/wordpress` and at least one of `https://wpackagist.org` or `https://release-belt.atomicsmash.co.uk` in repositories. A `.nucleus/config.yml` file is required.

The command will:

1. Ask if you want to send the monthly maintenance email to your client
2. Check project and (if sending email) global config; prompt for MailerSend API key and sender details if missing
3. Optionally create a maintenance branch from `main` (e.g. `feature/🛠️-Maintenance-YYYY-MM-DD`)
4. Optionally send the "starting maintenance" email (Template 1) via MailerSend
5. Check wpackagist and release-belt plugins for updates; show changelog; apply updates (including release-belt flow: plugins.atomicsmash.co.uk + SSH update script)
6. Optionally commit changes to the maintenance branch with a generated commit message
7. Optionally deploy to staging (create release branch, merge maintenance, run `npm run deploy`)
8. Prompt you to check staging and create a PR (e.g. via Sourcetree or GitLab)
9. Pull `main`, then optionally deploy to production (`npm run deploy:prod`)
10. Optionally send the "maintenance complete" email (Template 2) via MailerSend
11. Finish and clear workflow state

Progress is stored in `.nucleus/plugin-workflow.yml` so you can resume if interrupted. Use `--no-resume` to start fresh.

**Config:**

- **Project** `.nucleus/config.yml`: `plugins_update.exclude` (plugin slugs to skip), `maintenance_email.client_name`, `maintenance_email.client_email`, `maintenance_email.cc`
- **Global** `~/.config/nucleus/config.yml` (or `~/.nucleus/config.yml`): `mailersend.api_key`, `mailersend.template_id`, `sender_email`, `developer_name`

### Theme Cleanup

[](#theme-cleanup)

Clean up themes by keeping only the active theme and its parent (if child theme):

```
nucleus theme:cleanup
```

The command will:

1. Check for active theme in `package.json` config (if exists)
2. If not found, prompt you to select the active theme from available themes
3. Detect if the active theme is a parent or child theme by reading `style.css`
4. If it's a child theme, identify and preserve the parent theme
5. Show a summary of themes to be deleted
6. Confirm deletion with the user
7. Delete all other themes while preserving the active theme and its parent (if applicable)

Template Files
--------------

[](#template-files)

The package includes template files that are copied during the project core setup. These files contain placeholders that are replaced with user input:

### Basic Project Settings

[](#basic-project-settings)

- `{{VENDOR_NAME}}` - Your vendor/organisation name
- `{{PROJECT_NAME}}` - Your project name (e.g. "The ABC Company")
- `{{PROJECT_DESCRIPTION}}` - Project description
- `{{PROJECT_LICENSE}}` - Project license (e.g., proprietary)
- `{{PROJECT_SLUG}}` - Project slug (auto-generated from project name if not specified, e.g. "the-abc-company")
- `{{THEME_NAME}}` - Theme name (selected from available themes in `wp-content/themes` or custom entry)

### Environment Configuration

[](#environment-configuration)

- `{{PHP_VERSION}}` - PHP version (e.g. `8.2`)
- `{{WORDPRESS_VERSION}}` - WordPress version (e.g. `6.7.2`)
- `{{WEB_ROOT}}` - Web root path (e.g. `public/`)
- `{{WORDPRESS_INSTALL_PATH}}` - WordPress installation directory (e.g. `wp`)
- `{{WORDPRESS_TABLE_PREFIX}}` - WordPress database table prefix (e.g. `wp_`)
- `{{KINSTA_FOLDER}}` - Kinsta folder name (e.g. `theabccompany_123`)

### Git Configuration

[](#git-configuration)

- `{{GIT_REMOTE_SSH}}` - Git remote SSH URL
- `{{GIT_DEFAULT_BRANCH}}` - Git default branch (e.g. `main`)

### Development Environment

[](#development-environment)

- `{{DB_NAME_DEVELOPMENT}}` - Development database name
- `{{DB_USER_DEVELOPMENT}}` - Development database user
- `{{DB_PASSWORD_DEVELOPMENT}}` - Development database password
- `{{DB_HOST_DEVELOPMENT}}` - Development database host

### Staging Environment

[](#staging-environment)

- `{{DB_NAME_STAGING}}` - Staging database name
- `{{DB_USER_STAGING}}` - Staging database user
- `{{DB_PASSWORD_STAGING}}` - Staging database password
- `{{DB_HOST_STAGING}}` - Staging database host
- `{{STAGING_SSH_HOST}}` - Staging SSH host
- `{{STAGING_SSH_USER}}` - Staging SSH user
- `{{STAGING_SSH_PORT}}` - Staging SSH port
- `{{STAGING_WEB_ROOT}}` - Staging web root path
- `{{STAGING_URL}}` - Staging URL

### Production Environment

[](#production-environment)

- `{{DB_NAME_PRODUCTION}}` - Production database name
- `{{DB_USER_PRODUCTION}}` - Production database user
- `{{DB_PASSWORD_PRODUCTION}}` - Production database password
- `{{DB_HOST_PRODUCTION}}` - Production database host
- `{{PRODUCTION_SSH_HOST}}` - Production SSH host
- `{{PRODUCTION_SSH_USER}}` - Production SSH user
- `{{PRODUCTION_SSH_PORT}}` - Production SSH port
- `{{PRODUCTION_WEB_ROOT}}` - Production web root path
- `{{PRODUCTION_URL}}` - Production URL

### WordPress Security Keys

[](#wordpress-security-keys)

The package automatically generates secure WordPress security keys using the [rbdwllr/wordpress-salts-generator](https://packagist.org/packages/rbdwllr/wordpress-salts-generator) package. These include:

- `{{AUTH_KEY}}` - WordPress authentication key
- `{{SECURE_AUTH_KEY}}` - WordPress secure authentication key
- `{{LOGGED_IN_KEY}}` - WordPress logged in key
- `{{NONCE_KEY}}` - WordPress nonce key
- `{{AUTH_SALT}}` - WordPress authentication salt
- `{{SECURE_AUTH_SALT}}` - WordPress secure authentication salt
- `{{LOGGED_IN_SALT}}` - WordPress logged in salt
- `{{NONCE_SALT}}` - WordPress nonce salt

### External Services

[](#external-services)

- `{{MAILTRAP_USERNAME}}` - MailTrap username
- `{{MAILTRAP_PASSWORD}}` - MailTrap password
- `{{RELEASE_BELT_USERNAME}}` - Release Belt username
- `{{RELEASE_BELT_PASSWORD}}` - Release Belt password
- `{{ACF_USERNAME}}` - ACF Pro username
- `{{ACF_PASSWORD}}` - ACF Pro password

During the project core setup, you'll be prompted for all these values with sensible defaults provided. For WordPress security keys, you can choose to generate them automatically or enter them manually.

Requirements
------------

[](#requirements)

- PHP 7.4 or higher
- WordPress installation
- Composer

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE) for more information.

###  Health Score

23

—

LowBetter than 26% of packages

Maintenance65

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity18

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/2117552?v=4)[Atomic Smash](/maintainers/atomicsmash)[@AtomicSmash](https://github.com/AtomicSmash)

---

Top Contributors

[![MeMattStone](https://avatars.githubusercontent.com/u/1451037?v=4)](https://github.com/MeMattStone "MeMattStone (24 commits)")

### Embed Badge

![Health badge](/badges/atomicsmash-nucleus-cli/health.svg)

```
[![Health](https://phpackages.com/badges/atomicsmash-nucleus-cli/health.svg)](https://phpackages.com/packages/atomicsmash-nucleus-cli)
```

###  Alternatives

[seld/cli-prompt

Allows you to prompt for user input on the command line, and optionally hide the characters they type

24726.4M22](/packages/seld-cli-prompt)[illuminate/console

The Illuminate Console package.

13045.3M6.2k](/packages/illuminate-console)[styleci/cli

The CLI tool for StyleCI

71464.1k9](/packages/styleci-cli)[winbox/args

Windows command-line formatter

20718.9k21](/packages/winbox-args)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)