Lesson 0003 · ~12 minutes

Everyday loop: install → init → map → run

One skill: walk the path from a moon binary to moon run app:lint — install, moon init, project discovery, then targets — without memorizing every config knob.

1. Install the binary

moon ships as a single binary (install guide). Common paths:

• proto (suggested): proto install moon — multi-version; pin with .prototools (e.g. moon = "2.0.0").
• Shell installer: curl script → ~/.moon/bin + put it on PATH.
• npm package: @moonrepo/cli as a root devDependency. If both global and repo package exist, the repo package version wins when you invoke moon — useful for pinning the team.

Upgrade later via proto install moon --pin or moon upgrade (for ~/.moon/bin installs).

2. Init the workspace

After install: setup workspace + moon init.

$ moon init
# prototype: moon init --minimal

• Creates .moon/ (or .config/moon) — the workspace root marker.
• Writes required .moon/workspace.*.
• Appends ignore patterns to .gitignore; infers VCS.

The workspace owns VCS integration, tree-wide config, the project graph, and running the action graph. moon needs a VCS (default git) for hashing and affected runs — set vcs.defaultBranch if yours is main not master.

3. Map projects (discovery)

Three patterns (all official):

• Map: client: 'apps/client' — stable IDs you type in targets.
• Globs: - 'apps/*' — IDs from folder names (collision risk).
• Both: globs: + sources: for exceptions.

Check a project: moon project client. Wrong path → error. Config tasks with shared .moon/tasks/** and/or per-project moon.* (lesson 2 inheritance still applies).

4. Run targets

Everyday command: moon run (alias moon r). Run a task spells the pipeline:

1. Build action graph (DAG).
2. Insert task deps, then the primary target.
3. Run topo-sorted, parallel where possible.
4. Hash each task → cache hit short-circuits, miss runs + caches.

$ moon run app:build
$ moon run client:dev server:dev
$ moon run :test              # all projects
$ moon run '~:test'           # closest project (cwd)
$ moon run app:build --affected
$ moon run app:build -- --force   # args after -- go to the tool

Default is fail-fast (one failure aborts the graph). --affected only runs when VCS-touched files intersect the task’s inputs — the anti-“full CI every push” lever from lesson 1.

5. Trace it once (mental dry-run)

6. Practice

Equal-length options. Retrieve the loop, not the whole manual.

7. Primary source

Recommended path (in order): Install → Setup workspace → Create a project → Run a task.

Keep the loop sheet open when you try this on a real repo (optional hands-on; quiz first is fine).