Moon CLI

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.

Package Information

• Package Name: @moonrepo/cli
• Package Type: npm
• Language: JavaScript (CommonJS)
• Installation: npm install @moonrepo/cli or yarn add @moonrepo/cli
• Binary: Provides moon command globally after installation

Core Imports

For programmatic usage:

const { findMoonExe } = require("@moonrepo/cli/utils");

Basic Usage

CLI Usage

After installation, use the moon command directly:

# Initialize moon in your repository
moon init

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

# Run a task across all projects
moon run :test

# Check project health
moon check

# View project information
moon project myapp

Programmatic Usage

const { findMoonExe } = require("@moonrepo/cli/utils");
const { spawn } = require("child_process");

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

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

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

Architecture

The package consists of three main components:

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

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.

Capabilities

Platform Detection and Binary Resolution

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

function findMoonExe(): string;

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

Post-Install Setup

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

// Internal post-install functionality (not exported)
function setupBinary(): void;

setupBinary(): Internal function that runs during package installation to link or copy the platform-specific binary to the local package directory. This process:

• Detects platform/architecture (including libc family on Linux)
• Resolves the correct optional dependency package
• Creates hard links (or copies if linking fails) from the binary location
• Sets executable permissions (755 on Unix systems)

CLI Command Interface

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

Environment Commands

moon init
moon completions

• init: Initialize a new moon repository or toolchain by scaffolding configuration files
• completions: Generate command completions for your current shell

Toolchain Management

moon bin <tool>
moon setup
moon teardown
moon toolchain <subcommand>
moon node <subcommand>

• 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
• setup: Setup environment by installing all configured tools
• teardown: Teardown environment by uninstalling all tools and deleting temporary files
• toolchain: Manage toolchain plugins (has subcommands)
• node: Special Node.js commands (has subcommands)

Project Operations

moon project <id>
moon project-graph [id]
moon task <target>
moon task-graph [id]
moon action-graph [target]
moon sync [subcommand]

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

Code Generation

moon generate
moon templates

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

Task Execution

moon run [...targets]
moon check
moon ci

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

Plugin System

moon ext

• ext: Execute an extension plugin

Utility Commands

moon clean
moon docker <subcommand>
moon mcp
moon migrate <subcommand>
moon query <subcommand>
moon upgrade

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

Alternative Execution Interface

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

moonx <task-target>

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

Types

// Platform detection constants (internal use, not exported)
const isLinux: boolean;
const isMacos: boolean; 
const isWindows: boolean;
const platform: string;
const arch: string;
const triple: string;

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.

Error Handling

The package throws errors in the following scenarios:

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

Platform Support

Supports multiple platforms through optional dependencies:

• Linux: x64 and arm64 architectures with both GNU and musl libc
• macOS: x64 and arm64 architectures
• Windows: x64 architecture with MSVC runtime

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

Installation Behavior

The package includes a post-install script that:

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

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