MPLX CLI - Candy Machine Commands

The MPLX CLI provides comprehensive support for creating and managing MPL Core Candy Machines on Solana. These commands allow you to create NFT collections with configurable minting rules, upload assets, and manage the entire candy machine lifecycle through an intuitive command-line interface.

Quick Start

Get started quickly with the interactive wizard:

mplx cm create --wizard

This single command handles everything to create a candy machine: asset validation, upload, candy machine creation including guard configuration, item insertion with progress tracking.

Command Overview

Command	Purpose	Key Features
`create`	Create a new candy machine	Interactive wizard, template generation, manual config
`upload`	Upload assets to storage	Intelligent caching, progress tracking, validation
`insert`	Insert items into candy machine	Smart loading detection, batch processing
`validate`	Validate asset cache	Comprehensive validation, error reporting
`fetch`	Fetch candy machine info	Display configuration, guard settings, status
`withdraw`	Withdraw and delete	Clean withdrawal, balance recovery

Key Features

Interactive Wizard

Guided Setup: Step-by-step candy machine creation
Asset Validation: Comprehensive file and metadata validation
Progress Tracking: Real-time indicators for all operations
Error Recovery: Detailed error messages with actionable guidance

Intelligent Asset Management

Smart Caching: Reuses existing uploads when possible
Batch Processing: Efficient asset upload and insertion
File Validation: Ensures proper naming and metadata format
Collection Support: Automatic collection creation

Flexible Configuration

Guard Support: All Core Candy Machine guards supported
Guard Groups: Create different minting phases with distinct rules
Template Generation: Quick directory structure setup
Manual Configuration: Advanced users can create custom configs

Directory Structure

All candy machine commands work from a candy machine asset directory with this structure:

my-candy-machine/
├── assets/
│   ├── 0.png              # Image files (PNG, JPG)
│   ├── 0.json             # Metadata files
│   ├── 1.png
│   ├── 1.json
│   ├── ...
│   ├── collection.png      # Collection image
│   └── collection.json     # Collection metadata
├── asset-cache.json        # Asset upload cache (generated)
└── cm-config.json          # Candy machine configuration (generated when using the wizard)

Workflow Options

Option 1: Wizard Mode (Recommended)

Perfect for beginners and most use cases:

mplx cm create --wizard

What it does:

Validates assets and configuration
Uploads all assets with progress tracking
Creates the candy machine on-chain
Inserts all items with transaction progress
Provides comprehensive completion summary

Option 2: Manual Mode (Advanced)

For advanced users who want full control:

# 1. Set up directory and config manually
mkdir my-candy-machine && cd my-candy-machine
# (create assets/ directory and add your assets)

# 2. Upload assets
mplx cm upload

# 3. Create candy machine
mplx cm create

# 4. Insert items
mplx cm insert

# 5. Validate (optional)
mplx cm validate

Guard Configuration

The CLI supports all Core Candy Machine guards and guard groups:

Global Guards

{
  "guardConfig": {
    "solPayment": {
      "lamports": 1000000000,
      "destination": "111111111111111111111111111111111"
    },
    "mintLimit": {
      "id": 1,
      "limit": 1
    }
  }
}

Guard Groups (Minting Phases)

{
  "groups": [
    {
      "label": "wl",
      "guards": {
        "allowList": {
          "merkleRoot": "MerkleRootHash..."
        },
        "solPayment": {
          "lamports": 500000000,
          "destination": "111111111111111111111111111111111"
        }
      }
    },
    {
      "label": "public",
      "guards": {
        "solPayment": {
          "lamports": 1000000000,
          "destination": "111111111111111111111111111111111"
        }
      }
    }
  ]
}

Available Guards

The CLI supports all Core Candy Machine guards:

Payment Guards: solPayment, solFixedFee, tokenPayment, token2022Payment, nftPayment, assetPayment, assetPaymentMulti

Access Control: addressGate, allowList, nftGate, tokenGate, assetGate, programGate, thirdPartySigner

Time-Based: startDate, endDate

Limits: mintLimit, allocation, nftMintLimit, assetMintLimit, redeemedAmount

Burn Guards: nftBurn, tokenBurn, assetBurn, assetBurnMulti

Special: botTax, edition, vanityMint

Freeze Guards: freezeSolPayment, freezeTokenPayment

For detailed guard documentation, see the Core Candy Machine Guards reference.

Best Practices

🎯 Directory Organization

Keep each candy machine in its own directory
Use descriptive directory names
Maintain consistent asset naming (0.png, 1.png, etc.)
Back up your candy machine directories

📁 Asset Preparation

Use consistent naming (0.png, 1.png, etc.)
Ensure metadata JSON files match image files
Validate image formats (PNG, JPG supported)
Keep file sizes reasonable (< 10MB recommended)
Include collection.json with a valid "name" field

⚙️ Configuration

Test on devnet before mainnet
Use the wizard for guided configuration
Back up configuration files
Document guard settings
Consider adding at least one guard or guard group

🚀 Deployment

Verify candy machine creation
Test minting functionality
Monitor transaction status
Keep explorer links for verification

Core Candy Machine Overview - Understanding MPL Core Candy Machines
Core Candy Machine Guards - Complete guard reference
CLI Installation - Setting up the MPLX CLI
CLI Configuration - Wallet and RPC setup

Next Steps

Install the CLI if you haven't already
Create your first candy machine using the wizard
Explore guard configuration for advanced minting rules
Learn about guard groups for phased launches