Skip to content

Commit 0ae29b8

Browse files
MarkSackerbergcoderabbitai[bot]
MarkSackerberg
and
coderabbitai[bot]
authored
core cm cli docs (#397)
* initial cm docs * markdownlint * Apply suggestion from @coderabbitai[bot] Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * codeRabbit --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
1 parent 2cfbbd2 commit 0ae29b8

File tree

13 files changed

+821
-7
lines changed

13 files changed

+821
-7
lines changed

‎src/components/products/cli/index.js‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,39 @@ export const cli = {
7575
},
7676
],
7777
},
78+
{
79+
title: 'Candy Machine Commands',
80+
links: [
81+
{
82+
title: 'Overview',
83+
href: '/cli/cm',
84+
},
85+
{
86+
title: 'Create Candy Machine',
87+
href: '/cli/cm/create',
88+
},
89+
{
90+
title: 'Upload Assets',
91+
href: '/cli/cm/upload',
92+
},
93+
{
94+
title: 'Insert Items',
95+
href: '/cli/cm/insert',
96+
},
97+
{
98+
title: 'Validate Cache',
99+
href: '/cli/cm/validate',
100+
},
101+
{
102+
title: 'Fetch Information',
103+
href: '/cli/cm/fetch',
104+
},
105+
{
106+
title: 'Withdraw',
107+
href: '/cli/cm/withdraw',
108+
},
109+
],
110+
},
78111
{
79112
title: 'Toolbox',
80113
links: [

‎src/pages/cli/cm/create.md‎

Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
---
2+
title: "Create Candy Machine"
3+
metaTitle: "MPLX CLI - Create Candy Machine Command"
4+
description: "Create MPL Core Candy Machines using the MPLX CLI. Interactive wizard mode with validation, asset upload, and complete setup automation."
5+
---
6+
7+
The `mplx cm create` command creates a new MPL Core Candy Machine with configurable settings and asset uploads. It offers both an interactive wizard for beginners and manual configuration for advanced users.
8+
9+
## Usage
10+
11+
```bash
12+
# Interactive wizard (recommended)
13+
mplx cm create --wizard
14+
15+
# Create directory template
16+
mplx cm create --template
17+
18+
# Manual creation (requires existing cm-config.json)
19+
mplx cm create
20+
```
21+
22+
## Prerequisite Assets
23+
24+
Independent of the Mode (Wizard or Manual) you choose you will need your assets prepared. If you want to play around with dummy assets you can create them using `mplx cm create --template`. All the image and metadata files should be in their own `assets` folder.
25+
26+
*Image Files:*
27+
28+
- **Formats**: PNG, JPG
29+
- **Naming**: Sequential (0.png, 1.png, 2.png, ...)
30+
31+
*Metadata Files:*
32+
33+
- **Format**: JSON
34+
- **Naming**: Matching image files (0.json, 1.json, 2.json, ...)
35+
- **Schema**: Standard [Metaplex Core metadata format](/core/json-schema)
36+
37+
*Collection Files:*
38+
39+
- **collection.png**: Collection image
40+
- **collection.json**: Collection metadata
41+
42+
## Template Mode
43+
44+
Create a basic directory structure to get started:
45+
46+
```bash
47+
mplx cm create --template
48+
```
49+
50+
This creates the following structure, but not the candy machine.
51+
52+
```text
53+
candy-machine-template/
54+
├── assets/
55+
│ ├── 0.png # Example image
56+
│ ├── 0.json # Example metadata
57+
│ ├── collection.png # Example collection image
58+
│ └── collection.json # Example collection metadata
59+
└── cm-config.json # Example configuration
60+
```
61+
62+
After creating the template:
63+
64+
1. Replace example assets with your actual files
65+
2. Update the configuration in `cm-config.json`
66+
3. Run `mplx cm create` to deploy
67+
68+
## Interactive Wizard Mode
69+
70+
The wizard provides a guided, user-friendly experience with comprehensive validation and progress tracking. **This is the recommended approach for most users.**
71+
72+
### Wizard Workflow
73+
74+
1. Project Setup
75+
2. Asset Discovery & Validation
76+
3. Collection Configuration
77+
4. Candy Machine and Candy Guard Settings
78+
5. Asset Upload & Processing
79+
6. Candy Machine Creation
80+
7. Item Insertion
81+
82+
## Manual Configuration Mode
83+
84+
For advanced users who want full control over the configuration process.
85+
86+
### Prerequisites
87+
88+
1. **Candy machine asset directory** with proper structure
89+
2. **Manually created `cm-config.json`** with required configuration. See below for an example
90+
3. **Prepared assets** in the `assets/` directory in a structure as shown below
91+
92+
### Directory Structure
93+
94+
```text
95+
my-candy-machine/
96+
├── assets/
97+
│ ├── 0.png
98+
│ ├── 0.json
99+
│ ├── 1.png
100+
│ ├── 1.json
101+
│ ├── ...
102+
│ ├── collection.png
103+
│ └── collection.json
104+
└── cm-config.json # Required
105+
```
106+
107+
### Configuration File Format
108+
109+
Create `cm-config.json` with this structure:
110+
111+
```json
112+
{
113+
"name": "My Candy Machine",
114+
"config": {
115+
"collection": "CollectionPublicKey...", // existing collection
116+
"itemsAvailable": 100,
117+
"isMutable": true,
118+
"isSequential": false,
119+
"guardConfig": {
120+
"solPayment": {
121+
"lamports": 1000000000,
122+
"destination": "111111111111111111111111111111111"
123+
},
124+
"mintLimit": {
125+
"id": 1,
126+
"limit": 1
127+
}
128+
},
129+
"groups": [
130+
{
131+
"label": "wl",
132+
"guards": {
133+
"allowList": {
134+
"merkleRoot": "MerkleRootHash..."
135+
},
136+
"solPayment": {
137+
"lamports": 500000000,
138+
"destination": "111111111111111111111111111111111"
139+
}
140+
}
141+
}
142+
]
143+
}
144+
}
145+
```
146+
147+
### Manual Workflow
148+
149+
```bash
150+
# 1. Navigate to your candy machine directory
151+
cd ./my-candy-machine
152+
153+
# 2. Create candy machine using existing config
154+
mplx cm create
155+
156+
# 3. Upload assets to storage
157+
mplx cm upload
158+
159+
# 4. Insert items into candy machine
160+
mplx cm insert
161+
162+
# 5. Validate setup (optional)
163+
mplx cm validate
164+
```
165+
166+
## Configuration Options
167+
168+
### Core Settings
169+
170+
| Setting | Description | Required |
171+
|---------|-------------|----------|
172+
| `name` | Display name for the candy machine | ✅ |
173+
| `itemsAvailable` | Total number of items to mint | ✅ |
174+
| `isMutable` | Whether NFTs can be updated after minting | ✅ |
175+
| `isSequential` | Whether to mint items in order | ✅ |
176+
| `collection` | Existing collection address (optional) | ❌ |
177+
178+
### Guard Configuration
179+
180+
**Global Guards** (`guardConfig`):
181+
182+
- Apply to all groups and the candy machine as a whole
183+
- Cannot be overridden by group guards
184+
- Useful for universal restrictions
185+
186+
**Guard Groups** (`groups`):
187+
188+
- Apply only to specific groups
189+
- Allow different rules per minting phase
190+
- Group labels limited to 6 characters maximum
191+
192+
### Common Guard Examples
193+
194+
#### Basic Public Sale
195+
196+
```json
197+
{
198+
"guardConfig": {
199+
"solPayment": {
200+
"lamports": 1000000000,
201+
"destination": "YourWalletAddress..."
202+
},
203+
"mintLimit": {
204+
"id": 1,
205+
"limit": 1
206+
}
207+
}
208+
}
209+
```
210+
211+
#### Whitelist Phase
212+
213+
```json
214+
{
215+
"groups": [
216+
{
217+
"label": "wl",
218+
"guards": {
219+
"allowList": {
220+
"merkleRoot": "MerkleRootHash..."
221+
},
222+
"solPayment": {
223+
"lamports": 500000000,
224+
"destination": "YourWalletAddress..."
225+
}
226+
}
227+
}
228+
]
229+
}
230+
```
231+
232+
### Getting Help
233+
234+
- Use `mplx cm create --help` for command options
235+
- Join the [Metaplex Discord](https://discord.gg/metaplex) for support
236+
237+
## Related Commands
238+
239+
- [`mplx cm upload`](/cli/cm/upload) - Upload assets to storage
240+
- [`mplx cm insert`](/cli/cm/insert) - Insert items into candy machine
241+
- [`mplx cm validate`](/cli/cm/validate) - Validate asset cache
242+
- [`mplx cm fetch`](/cli/cm/fetch) - View candy machine information
243+
244+
## Next Steps
245+
246+
1. **[Upload assets](/cli/cm/upload)** if created manually
247+
2. **[Insert items](/cli/cm/insert)** to load assets into candy machine
248+
3. **[Validate your setup](/cli/cm/validate)** to ensure everything works
249+
4. **[Learn about guards](/core-candy-machine/guards)** for advanced configuration

‎src/pages/cli/cm/fetch.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: "Fetch Information"
3+
metaTitle: "MPLX CLI - Fetch Candy Machine Information"
4+
description: "Fetch and display MPL Core Candy Machine information using the MPLX CLI. View configuration, guard settings, item status, and deployment details."
5+
---
6+
7+
The `mplx cm fetch` command retrieves and displays comprehensive information about a candy machine, including configuration, guard settings, item status, and deployment details. This command is essential for monitoring and verifying your candy machine setup.
8+
9+
## Usage
10+
11+
```bash
12+
# Fetch info from current candy machine directory
13+
mplx cm fetch
14+
15+
# Fetch specific candy machine by address
16+
mplx cm fetch <candy_machine_address>
17+
18+
```
19+
20+
The fetch command supports an additional flag for detailed information:
21+
22+
- `--items`: Include detailed information about loaded items
23+
24+
## Related Commands
25+
26+
- [`mplx cm create`](/cli/cm/create) - Create the candy machine to fetch
27+
- [`mplx cm insert`](/cli/cm/insert) - Load items (affects item counts)
28+
- [`mplx cm validate`](/cli/cm/validate) - Validate cache vs on-chain data
29+
- [`mplx cm withdraw`](/cli/cm/withdraw) - Clean up after checking status

0 commit comments

Comments
 (0)