Skip to main content
The moon setup command can be used to setup the developer and pipeline environments. It achieves this by downloading and installing all configured toolchains. 
$ moon setup
Output: 
▪▪▪▪ Installing toolchains...
✓ Setup 3 toolchains successfully!
:::info This command should rarely be used, as the environment is automatically setup when running other commands, like detecting affected projects, running a task, or generating a build artifact. :::

​
How It Works

The setup command:
  1. Installs proto - Ensures proto (the toolchain manager) is available
  2. Reads toolchain config - Loads configuration from .moon/toolchains.*
  3. Installs toolchains - Downloads and installs each configured toolchain:
    • Node.js
    • Rust
    • Go
    • Python
    • Deno
    • Bun
    • Custom toolchains
  4. Verifies installation - Ensures toolchains are properly installed

​
Automatic Setup

Moon automatically runs setup when needed, such as:
  • Running tasks via moon run
  • Querying projects with moon query
  • Generating code with moon generate
  • Running checks with moon check
  • CI workflows with moon ci
You only need to manually run moon setup if you want to:
  • Pre-install toolchains before running tasks
  • Verify toolchain configuration
  • Troubleshoot installation issues
  • Set up a fresh development environment

​
Output Messages

​
Success

✓ Setup 3 toolchains successfully!
All toolchains were installed without errors.

​
Already Up to Date

ⓘ All toolchains are already up to date!
Toolchains are already installed at the configured versions.

​
No Toolchains Configured

ⓘ Unable to setup, no toolchains are configured!
No toolchains are defined in .moon/toolchains.* configuration.

​
Partial Failure

⚠ Setup toolchains with 2 passed, 0 skipped, and 1 failed
Some toolchains failed to install. Check error messages for details.

​
Toolchain Configuration

Toolchains are configured in .moon/toolchains.yml: 
node:
  version: '20.0.0'
  packageManager: 'npm'

rust:
  version: '1.75.0'

go:
  version: '1.21.0'

​
Using with proto

If moon is installed via proto, toolchains are managed by proto: 
# Install moon with proto
$ proto install moon

# Toolchains are automatically managed
$ moon setup
See proto documentation for more details.

​
CI/CD Usage

In CI environments, setup happens automatically: 
# GitHub Actions
- name: Setup moon
  uses: moonrepo/setup-toolchain@v0

- name: Run tasks
  run: moon run build
  # Setup happens automatically before running tasks
For explicit setup: 
- name: Explicitly setup toolchains
  run: moon setup

- name: Run tasks
  run: moon run build

​
Troubleshooting

​
Toolchain Installation Fails

If a toolchain fails to install:
  1. Check internet connectivity
  2. Verify the version exists and is valid
  3. Check filesystem permissions
  4. Review proto logs: ~/.proto/logs/
  5. Try installing the toolchain directly with proto: 
    proto install node 20.0.0

​
Version Conflicts

If you have existing toolchain installations:
  1. Moon uses proto to manage versions
  2. Proto installs to ~/.proto/tools/
  3. These don’t conflict with system installations
  4. Moon tasks use proto-managed versions

​
Offline Installation

Moon requires internet to download toolchains. For offline environments:
  1. Pre-install toolchains on a connected machine
  2. Copy ~/.proto/ directory to offline machine
  3. Or use system-installed toolchains by setting version: system

​
Examples

​
Basic setup

$ moon setup

​
Setup in CI

# Explicitly setup before tasks
$ moon setup && moon run build

​
Verify setup worked

$ moon setup
$ moon check --all

​
Configuration

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us