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.