setup

Setup the developer environment by installing all configured toolchains

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

• * in .moon/toolchains.*
• Toolchains guide - Configure toolchains
• proto documentation - Toolchain manager

See Also

• moon teardown - Uninstall toolchains
• moon upgrade - Upgrade moon itself
• moon check - Verify workspace health