Skip to main content
The moon query command provides a suite of sub-commands for querying information about your moon workspace using a powerful query language. All query commands output JSON for easy integration with other tools.

​
Sub-commands

​
moon query projects

Query for projects within the project graph. Results can be filtered using query statements or option flags. 
# Find all projects
$ moon query projects

# Find all projects with an id that matches "react"
$ moon query projects --id react
$ moon query projects "project~react"

# Find all projects with a `lint` or `build` task
$ moon query projects --tasks "lint|build"
$ moon query projects "task=[lint,build]"

# Find all TypeScript projects
$ moon query projects --language typescript
$ moon query projects "language=typescript"

​
Output structure

{
  projects: Project[],
  options: QueryOptions,
}

​
Arguments

  • [query] - An optional query statement to filter projects. When provided, all filter options are ignored.

​
Options

Affected:
  • --affected - Filter projects that have been affected by changed files
  • --downstream - Include downstream dependents of queried projects. Supports “none” (default), “direct”, “deep”
  • --upstream - Include upstream dependencies of queried projects. Supports “none” (default), “direct”, “deep”
Filters (all values are case-insensitive regex patterns):
  • --alias <regex> - Filter projects that match this alias
  • --id <regex> - Filter projects that match this ID/name
  • --language <regex> - Filter projects of this programming language
  • --layer <regex> - Filter projects of this layer
  • --source <regex> - Filter projects that match this source path
  • --stack <regex> - Filter projects of this tech stack
  • --tags <regex> - Filter projects that have the following tags
  • --tasks <regex> - Filter projects that have the following tasks

​
moon query tasks

Query for tasks within the task graph, grouped by project. Results can be filtered using query statements or option flags. 
# Find all tasks grouped by project
$ moon query tasks

# Find all tasks from projects with an id that matches "react"
$ moon query tasks --project react
$ moon query tasks "task~react"

# Find all build tasks
$ moon query tasks --id build
$ moon query tasks "task=build"

# Find all tasks that use npm
$ moon query tasks --toolchain npm

​
Output structure

{
  tasks: Record<string, Record<string, Task>>,
  options: QueryOptions,
}

​
Arguments

  • [query] - An optional query statement to filter tasks. When provided, all filter options are ignored.

​
Options

Affected:
  • --affected - Filter tasks that have been affected by changed files
  • --downstream - Include downstream dependents of queried tasks. Supports “none” (default), “direct”, “deep”
  • --upstream - Include upstream dependencies of queried tasks. Supports “none”, “direct”, “deep” (default)
Filters (all values are case-insensitive regex patterns):
  • --command <regex> - Filter tasks that match this command
  • --id <regex> - Filter tasks that match this ID
  • --project <regex> - Filter tasks that belong to this project
  • --script <regex> - Filter tasks that match this script
  • --toolchain <regex> - Filter tasks of this toolchain
  • --type <regex> - Filter tasks of this type

​
moon query affected

Query for affected projects and tasks based on changed files between revisions. 
# Find all affected projects and tasks
$ moon query affected

# Find affected items between two git references
$ moon query affected --base main --head feature-branch

# Find affected items with upstream dependencies
$ moon query affected --upstream deep

​
Arguments

Refer to the query affected documentation for detailed information.

​
moon query changed-files

Query for changed files between VCS revisions. 
# Find all changed files
$ moon query changed-files

# Find changed files between two git references
$ moon query changed-files --base main --head feature-branch

# Find changed files in the working directory
$ moon query changed-files --status staged

​
Arguments

Refer to the query changed-files documentation for detailed information.

​
Query language syntax

moon provides a powerful query language for filtering projects and tasks. The query language supports the following operators and patterns:

​
Operators

  • = - Exact match
  • ~ - Pattern match (regex)
  • != - Not equal
  • !~ - Not pattern match

​
Field queries

# Match projects where language equals "typescript"
$ moon query projects "language=typescript"

# Match projects where id contains "api"
$ moon query projects "project~api"

# Match projects with specific tags
$ moon query projects "tag=[frontend,react]"

​
Combining queries

Use && (AND) and || (OR) to combine multiple conditions: 
# Find TypeScript projects with a build task
$ moon query projects "language=typescript && task=build"

# Find projects that are either frontend or backend
$ moon query projects "tag=frontend || tag=backend"

# Complex query with multiple conditions
$ moon query projects "(language=typescript || language=javascript) && tag=production"

​
Arrays and lists

Use square brackets to match against arrays: 
# Match projects with lint OR build task
$ moon query projects "task=[lint,build]"

# Match projects with frontend OR backend tag
$ moon query projects "tag=[frontend,backend]"

​
Configuration

​
Examples

​
Finding affected projects

Use query commands with --affected to find what changed: 
# Find all affected projects
$ moon query projects --affected

# Pipe changed files to affected projects
$ moon query changed-files | moon query projects --affected

# Find affected projects with their dependents
$ moon query projects --affected --downstream deep

​
Piping to other tools

Since query commands output JSON, you can pipe results to tools like jq: 
# Extract just the project IDs
$ moon query projects | jq -r '.projects[].id'

# Count how many projects match
$ moon query projects --language typescript | jq '.projects | length'

# Get all task IDs from a specific project
$ moon query tasks --project api | jq -r '.tasks.api | keys[]'

​
CI/CD integration

Query commands are useful in CI/CD pipelines: 
#!/bin/bash

# Get list of affected projects
AFFECTED=$(moon query projects --affected | jq -r '.projects[].id')

# Run tests only for affected projects
for project in $AFFECTED; do
  moon run $project:test
done

Build docs developers (and LLMs) love

Get started for freeTalk to us