Skip to main content
The moon toolchain command provides utilities for managing toolchain plugins, including adding new toolchains and inspecting their capabilities. 
moon toolchain <subcommand>

​
Subcommands

​
add

Add and configure a toolchain plugin interactively. 
moon toolchain add <id> [plugin] [options]

​
Arguments

Plugin locator formats:
  • GitHub: source:github_user/repo
  • URL: source:https://example.com/plugin.wasm
  • File: file://./path/to/plugin.wasm

​
Options

​
How it works

  1. Loads the toolchain plugin using the provided or default locator
  2. Detects version from version files in the current directory (if supported)
  3. Runs interactive prompts to configure:
    • Toolchain version (if not detected)
    • Plugin-specific settings
    • Installation preferences
  4. Writes configuration to toolchains.yml or appropriate config file
  5. Displays success message with the config file path
The command intelligently:
  • Auto-detects versions from files like .node-version, rust-toolchain.toml, etc.
  • Provides context-aware prompts based on plugin capabilities
  • Validates settings against the plugin’s schema
  • Preserves existing configuration while adding new entries

​
info

Show detailed information about a toolchain plugin. 
moon toolchain info <id> [plugin]

​
Arguments

​
How it works

  1. Loads the toolchain plugin without requiring workspace configuration
  2. Analyzes plugin capabilities by checking implemented APIs
  3. Displays comprehensive information including:
    • Basic metadata (name, description, version)
    • Configuration schema and available settings
    • Tier 1 APIs (usage detection)
    • Tier 2 APIs (ecosystem integration)
    • Tier 3 APIs (tool management)
  4. Shows file patterns the plugin recognizes

​
Output sections

Toolchain - Basic information:
  • ID and title
  • Description
  • Plugin version
Configuration - Available settings:
  • Schema documentation
  • Setting types and defaults
  • Validation rules
Tier 1 - Usage detection - How the plugin identifies projects:
  • Config file globs (e.g., package.json, Cargo.toml)
  • Executable names (e.g., node, cargo)
  • Implemented APIs:
    • register_toolchain ✓ (required)
    • define_toolchain_config ○
    • initialize_toolchain ○
    • detect_version_files ○
    • parse_version_file ○
    • define_docker_metadata ○
    • scaffold_docker ○
    • prune_docker ○
    • sync_project ○
    • sync_workspace ○
    • extend_command ○
Tier 2 - Ecosystem integration - How the plugin integrates with the toolchain’s ecosystem:
  • Manifest files (e.g., package.json, Cargo.toml)
  • Lock files (e.g., package-lock.json, Cargo.lock)
  • Vendor directory (e.g., node_modules, target)
  • Implemented APIs:
    • extend_project_graph ○
    • extend_task_command ○
    • extend_task_script ○
    • define_requirements ○
    • locate_dependencies_root ○
    • install_dependencies ○
    • hash_task_contents ○
    • parse_lock ○
    • parse_manifest ○
    • setup_environment ○
Tier 3 - Tool management - How the plugin manages toolchain installation:
  • Implemented APIs:
    • register_tool ✓ (required)
    • load_versions ○
    • resolve_version ○
    • download_prebuilt ✓ (required)
    • unpack_archive ○
    • locate_executables ✓ (required)
    • setup_toolchain ○
    • teardown_toolchain ○
Legend: ✓ = implemented, ✓ (required) = implemented and required, ○ = not implemented

​
Examples

​
Add a Node.js toolchain

moon toolchain add node
Interactive prompts: 
? Enter a version, or leave blank for latest: 20.11.0
? Enable version syncing with .node-version files? Yes

✓ Added toolchain node to .moon/toolchains.yml!

​
Add a custom toolchain plugin

moon toolchain add custom source:github_org/custom-plugin

​
Add with minimal configuration

moon toolchain add rust --minimal
Skips optional prompts and uses defaults.

​
Add non-interactively

moon toolchain add python --yes
Perfect for automation or CI/CD: 
#!/bin/bash
moon toolchain add node --yes
moon toolchain add rust --yes
moon toolchain add python --yes

​
View Node.js plugin information

moon toolchain info node
Example output: 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Toolchain
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Node.js runtime and package managers

  ID       node
  Title    Node.js
  Version  1.2.3

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Configuration
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  version              string  
  plugin               string  
  installArgs          array   
  executeArgs          array   
  syncVersionManager   boolean

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Tier 1 - Usage detection
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Config files       package.json
  Executable names   node, nodejs

  ✓ register_toolchain
  ✓ define_toolchain_config
  ✓ initialize_toolchain
  ✓ detect_version_files
  ✓ parse_version_file
  ○ define_docker_metadata
  ○ scaffold_docker
  ...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Tier 2 - Ecosystem integration
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Manifest files    package.json
  Lock files        package-lock.json, yarn.lock, pnpm-lock.yaml
  Vendor directory  node_modules

  ✓ extend_project_graph
  ✓ install_dependencies
  ✓ parse_lock
  ✓ parse_manifest
  ...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Tier 3 - Tool management
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✓ register_tool
  ✓ download_prebuilt
  ✓ locate_executables
  ✓ load_versions
  ...

​
Inspect custom plugin capabilities

moon toolchain info custom source:github_org/custom-plugin

​
Compare plugin capabilities

# Compare Node.js vs Bun
moon toolchain info node > node-info.txt
moon toolchain info bun > bun-info.txt
diff node-info.txt bun-info.txt

​
Common workflows

​
Setting up a new workspace

# Initialize workspace
moon init

# Add required toolchains
moon toolchain add node
moon toolchain add rust

# Verify configuration
cat .moon/toolchains.yml

​
Exploring available toolchains

# Check what capabilities a toolchain provides
moon toolchain info python

# Determine if it supports your use case
moon toolchain info go | grep -A 20 "Tier 2"

​
Adding toolchains in CI/CD

# .github/workflows/setup.yml
name: Setup Toolchains

on: push

jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install moon
        run: curl -fsSL https://moonrepo.dev/install/moon.sh | bash
      
      - name: Add toolchains
        run: |
          moon toolchain add node --yes
          moon toolchain add rust --yes
      
      - name: Verify setup
        run: moon --version

​
Debugging plugin issues

# Get detailed plugin information
moon toolchain info problematic-toolchain > debug-info.txt

# Check if required APIs are implemented
cat debug-info.txt | grep "✓"

# Verify file patterns
cat debug-info.txt | grep -A 5 "Config files"

​
Configuration file updates

The toolchain add command updates your toolchains.yml: Before: 
# .moon/toolchains.yml
node:
  version: "18.0.0"
After running moon toolchain add rust --yes: 
# .moon/toolchains.yml
node:
  version: "18.0.0"

rust:
  version: "1.75.0"

​
Error handling

​
Plugin locator required

If the toolchain ID doesn’t have a default plugin: 
Error: Plugin locator is required for this toolchain.

Try: moon toolchain add <id> <plugin-locator>
Provide an explicit locator: 
moon toolchain add custom source:github_org/repo

​
Invalid plugin

If the plugin fails to load: 
Error: Failed to load toolchain plugin
Verify:
  • Plugin locator is correct
  • Plugin file exists and is accessible
  • Plugin is compatible with your moon version

​
Notes

The toolchain commands interact with moon’s plugin system. Make sure you have network access if loading plugins from remote sources.
Use moon toolchain info before adding a toolchain to understand what features it provides and how it integrates with your workflow.
When using custom plugins, ensure they are from trusted sources and are compatible with your moon version.

​
Exit codes

  • 0 - Command completed successfully
  • 1 - Plugin locator required or not provided
  • Non-zero - Error loading plugin or updating configuration

Build docs developers (and LLMs) love

Get started for freeTalk to us