Skip to main content
The moon run (or moon r) command will run one or many task targets and all of their dependencies in topological order. Each run will incrementally cache each task, improving speed and development times over time. 
# Run `lint` in project `app`
$ moon run app:lint

# Run `dev` in project `client` and `server`
$ moon run client:dev server:dev

# Run `test` in all projects
$ moon run :test

# Run `test` in the closest project, relative to the current working directory
$ moon run '~:test'

# Run `test` in all projects with tag `frontend`
$ moon run '#frontend:test'

# Run `format` in default project
$ moon run format

# Run `build` in projects matching the query
$ moon run :build --query "language=javascript && projectLayer=library"
:::info The default behavior for moon run is to “fail fast”, meaning that any failed task will immediately abort execution of the entire action graph. Use --on-failure continue for alternative behavior. :::

​
How it works

The moon run command is built on top of moon exec and provides a user-friendly interface for running tasks. It automatically:
  1. Resolves targets - Expands target locators (like :test or #tag:build) into concrete project:task pairs
  2. Builds dependency graph - Creates an action graph with all task dependencies in topological order
  3. Checks cache - Determines which tasks can be skipped based on cached results
  4. Executes pipeline - Runs tasks in parallel when possible, respecting dependencies
  5. Handles failures - Stops execution immediately on any task failure (bail mode)

​
Arguments

  • ...<target> - Task targets or project relative tasks to run. See target syntax for details.
  • [-- <args>] - Additional arguments to pass through to the underlying command.

​
Target syntax examples

SyntaxDescription
app:lintRun lint task in app project
:testRun test task in all projects
~:buildRun build in closest project
#frontend:lintRun lint in all projects with frontend tag
formatRun format task in default project

​
Options

Inherits all options from moon exec and pre-fills with: --on-failure=bail, --upstream=deep.

​
Common options

  • -f, --force - Force run and bypass cache, ignore changed files, and skip affected checks.
  • -i, --interactive - Run the pipeline and tasks interactively.
  • -s, --summary [LEVEL] - Print a summary of all actions that were ran in the pipeline.

​
Workflow options

  • --query <QUERY> - Filter tasks based on the result of a query expression.

​
Affected options

  • --affected [BY] - Only run tasks if affected by changed files. Optionally accepts “local” or “remote”.
  • --base <BASE> - Base branch, commit, or revision to compare against.
  • --head <HEAD> - Current branch, commit, or revision to compare with.
  • -g, --include-relations - Include graph relations for affected checks.
  • --status <STATUS> - Filter changed files based on a changed status.
  • --stdin - Accept changed files from stdin for affected checks.

​
Graph options

  • --downstream <DEPTH> - Control the depth of downstream dependents. Supports none (default), direct, deep.
  • --upstream <DEPTH> - Control the depth of upstream dependencies. Supports none, direct, deep (default).

​
Parallelism options

  • --job <INDEX> - Index of the current job (0 based) for splitting work across multiple CI jobs.
  • --job-total <TOTAL> - Total amount of jobs to run.

​
Examples

​
Run a single task

$ moon run app:build
Output: 
▪▪▪▪ app:build
  └─ /path/to/project/app (1.2s)

✓ Tasks completed in 1.2s

​
Run multiple tasks

$ moon run app:lint app:test app:build

​
Run task in all projects

$ moon run :test

​
Run with passthrough arguments

Pass arguments directly to the underlying command: 
$ moon run app:test -- --coverage --verbose

​
Run only affected tasks

Run tasks only for projects affected by changed files: 
$ moon run :build --affected

​
Run with custom base/head revisions

$ moon run :test --affected --base main --head feature-branch

​
Run with query filter

Filter tasks based on project metadata: 
$ moon run :build --query "language=typescript && projectType=library"

​
Force run without cache

Bypass cache and run all tasks fresh: 
$ moon run app:build --force

​
Run interactively

Run tasks with interactive input/output: 
$ moon run app:dev --interactive

​
Show execution summary

$ moon run :test --summary
Output: 
✓ Tasks completed in 5.2s

Summary:
  5 tasks completed
  2 tasks cached
  3 tasks executed

​
Environment variables

The following environment variables can be used as alternatives to command line options:
  • MOON_FORCE - Same as --force
  • MOON_AFFECTED - Same as --affected
  • MOON_BASE - Same as --base
  • MOON_HEAD - Same as --head
  • MOON_INCLUDE_RELATIONS - Same as --include-relations
  • MOON_JOB - Same as --job
  • MOON_JOB_TOTAL - Same as --job-total
  • MOON_NO_ACTIONS - Same as --no-actions
  • MOON_SUMMARY - Same as --summary

​
Configuration

The moon run command is configured through:

​
Comparison with moon exec

moon run is a simplified, user-friendly wrapper around moon exec with these defaults:
  • --on-failure=bail - Stops immediately on any failure
  • --upstream=deep - Includes all upstream dependencies
For more control over execution behavior, use moon exec directly.

Build docs developers (and LLMs) love

Get started for freeTalk to us