0
# Moon CLI
1

2
Moon CLI provides a JavaScript wrapper for moon, a repository management, organization, orchestration, and notification tool for the web ecosystem written in Rust. The CLI package enables developers to use moon through familiar package managers like npm, yarn, or pnpm, automatically handling platform-specific binary installation and execution.
3

4
## Package Information
5

6
- **Package Name**: @moonrepo/cli
7
- **Package Type**: npm
8
- **Language**: JavaScript (CommonJS)
9
- **Installation**: `npm install @moonrepo/cli` or `yarn add @moonrepo/cli`
10
- **Binary**: Provides `moon` command globally after installation
11

12
## Core Imports
13

14
For programmatic usage:
15

16
```javascript
17
const { findMoonExe } = require("@moonrepo/cli/utils");
18
```
19

20
## Basic Usage
21

22
### CLI Usage
23

24
After installation, use the `moon` command directly:
25

26
```bash
27
# Initialize moon in your repository
28
moon init
29

30
# Run a specific task in a project
31
moon run app:build
32

33
# Run a task across all projects
34
moon run :test
35

36
# Check project health
37
moon check
38

39
# View project information
40
moon project myapp
41
```
42

43
### Programmatic Usage
44

45
```javascript
46
const { findMoonExe } = require("@moonrepo/cli/utils");
47
const { spawn } = require("child_process");
48

49
// Get the path to the moon binary
50
const moonPath = findMoonExe();
51
console.log("Moon binary located at:", moonPath);
52

53
// Execute moon programmatically
54
const child = spawn(moonPath, ["run", "app:build"], {
55
  stdio: "inherit"
56
});
57

58
child.on("close", (code) => {
59
  console.log(`Moon process exited with code ${code}`);
60
});
61
```
62

63
## Architecture
64

65
The package consists of three main components:
66

67
- **Binary Wrapper**: `moon.js` and `moonx.js` executable scripts that spawn the native Rust binary
68
- **Platform Detection**: `utils.js` module that detects platform/architecture and locates the correct binary
69
- **Post-Install Setup**: Automatic binary installation and linking for the detected platform
70

71
The package automatically downloads and installs platform-specific binaries through optional dependencies, ensuring the correct native binary is available for Linux, macOS, and Windows systems.
72

73
## Capabilities
74

75
### Platform Detection and Binary Resolution
76

77
Core utility functions for locating and executing the moon binary across different platforms.
78

79
```javascript { .api }
80
function findMoonExe(): string;
81
```
82

83
**findMoonExe()**: Locates and returns the absolute path to the platform-specific moon binary executable. Throws an Error if the executable is not found.
84

85
### Post-Install Setup
86

87
The package includes a post-install script (`postinstall-old.js`) that automatically configures the binary after installation.
88

89
```javascript { .api }
90
// Internal post-install functionality (not exported)
91
function setupBinary(): void;
92
```
93

94
**setupBinary()**: Internal function that runs during package installation to link or copy the platform-specific binary to the local package directory. This process:
95
- Detects platform/architecture (including libc family on Linux)  
96
- Resolves the correct optional dependency package
97
- Creates hard links (or copies if linking fails) from the binary location
98
- Sets executable permissions (755 on Unix systems)
99

100
### CLI Command Interface
101

102
The moon binary provides extensive command-line functionality accessible through the JavaScript wrapper. All commands support standard CLI patterns with arguments, flags, and subcommands.
103

104
#### Environment Commands
105

106
```bash { .api }
107
moon init
108
moon completions
109
```
110

111
- **init**: Initialize a new moon repository or toolchain by scaffolding configuration files
112
- **completions**: Generate command completions for your current shell
113

114
#### Toolchain Management
115

116
```bash { .api }
117
moon bin <tool>
118
moon setup
119
moon teardown
120
moon toolchain <subcommand>
121
moon node <subcommand>
122
```
123

124
- **bin**: Return absolute path to a tool's binary within the toolchain. Returns non-zero exit code with no value if tool is not configured or installed
125
- **setup**: Setup environment by installing all configured tools  
126
- **teardown**: Teardown environment by uninstalling all tools and deleting temporary files
127
- **toolchain**: Manage toolchain plugins (has subcommands)
128
- **node**: Special Node.js commands (has subcommands)
129

130
#### Project Operations
131

132
```bash { .api }
133
moon project <id>
134
moon project-graph [id]
135
moon task <target>
136
moon task-graph [id]
137
moon action-graph [target]
138
moon sync [subcommand]
139
```
140

141
- **project (alias: p)**: Display information about a single project
142
- **project-graph (alias: pg)**: Display interactive graph of projects
143
- **task (alias: t)**: Display information about a single task
144
- **task-graph (alias: tg)**: Display interactive graph of tasks
145
- **action-graph (alias: ag)**: Display interactive dependency graph of all tasks and actions
146
- **sync**: Sync workspace to healthy state (has optional subcommands)
147

148
#### Code Generation
149

150
```bash { .api }
151
moon generate
152
moon templates
153
```
154

155
- **generate (alias: g)**: Generate and scaffold files from a pre-defined template
156
- **templates**: List all templates that are available for code generation
157

158
#### Task Execution
159

160
```bash { .api }
161
moon run [...targets]
162
moon check
163
moon ci
164
```
165

166
- **run (alias: r)**: Run one or many project tasks and their dependent tasks
167
- **check (alias: c)**: Run all build and test related tasks for the current project
168
- **ci**: Run all affected projects and tasks in a CI environment
169

170
#### Plugin System
171

172
```bash { .api }
173
moon ext
174
```
175

176
- **ext**: Execute an extension plugin
177

178
#### Utility Commands
179

180
```bash { .api }
181
moon clean
182
moon docker <subcommand>
183
moon mcp
184
moon migrate <subcommand>
185
moon query <subcommand>
186
moon upgrade
187
```
188

189
- **clean**: Clean the workspace and delete any stale or invalid artifacts
190
- **docker**: Operations for integrating with Docker and Dockerfile(s). Subcommands:
191
  - `file` - Generate a default Dockerfile for a project
192
  - `prune` - Remove extraneous files and folders within a Dockerfile
193
  - `scaffold` - Scaffold a repository skeleton for use within Dockerfile(s)
194
  - `setup` - Setup a Dockerfile by installing dependencies for necessary projects
195
- **mcp**: Start an MCP (model context protocol) server that can respond to AI agent requests
196
- **migrate**: Operations for migrating existing projects to moon (has subcommands)  
197
- **query**: Query information about moon, the environment, and pipeline (has subcommands)
198
- **upgrade (alias: up)**: Upgrade to the latest version of moon
199

200
### Alternative Execution Interface
201

202
The package also provides `moonx`, a simplified task runner interface:
203

204
```bash { .api }
205
moonx <task-target>
206
```
207

208
**moonx**: Automatically prefixes provided arguments with `run`, so `moonx app:build` is equivalent to `moon run app:build`.
209

210
## Types
211

212
```javascript { .api }
213
// Platform detection constants (internal use, not exported)
214
const isLinux: boolean;
215
const isMacos: boolean; 
216
const isWindows: boolean;
217
const platform: string;
218
const arch: string;
219
const triple: string;
220
```
221

222
**Platform Detection Constants**: Internal constants used by the utils module for determining the current system architecture and operating system. These are used internally by `findMoonExe()` but are not part of the public API.
223

224
## Error Handling
225

226
The package throws errors in the following scenarios:
227

228
- **Binary Not Found**: When `findMoonExe()` cannot locate the platform-specific moon binary
229
- **Execution Failures**: When spawned moon processes exit with non-zero status codes
230
- **Platform Detection Issues**: When the current platform/architecture combination is not supported
231

232
## Platform Support
233

234
Supports multiple platforms through optional dependencies:
235

236
- **Linux**: x64 and arm64 architectures with both GNU and musl libc
237
- **macOS**: x64 and arm64 architectures  
238
- **Windows**: x64 architecture with MSVC runtime
239

240
The correct binary is automatically selected during installation based on the detected platform and architecture.
241

242
## Installation Behavior
243

244
The package includes a post-install script that:
245

246
1. Detects the current platform and architecture
247
2. Locates the appropriate platform-specific binary from optional dependencies
248
3. Creates symlinks or copies the binary for local execution
249
4. Sets appropriate execution permissions (755 on Unix systems)
250

251
This ensures the moon binary is immediately available after package installation without additional setup steps.