Environment variables

moon interacts with environment variables in two directions:

• Variables moon sets — injected into the environment of every task process (and the child processes moon spawns), so your commands and scripts can read them.
• Variables moon reads — consumed from the shell to configure moon itself, override configuration settings, or toggle behavior.

info

moon embeds proto for toolchain management, so proto's own environment variables (like PROTO_HOME or PROTO_LOG) also apply. See the proto documentation for details. This page only documents moon's variables.

Variables moon sets

Within tasks

The following variables are injected into the environment of every task that moon runs, and can be referenced from within your commands, scripts, and .env files.

Variable	Description
MOON_CACHE_DIR	Absolute path to moon's cache directory (.moon/cache).
MOON_PROJECT_ID	ID of the project the running task belongs to.
MOON_PROJECT_ROOT	Absolute path to the project's root directory.
MOON_PROJECT_SOURCE	The project's source path, relative from the workspace root.
MOON_PROJECT_SNAPSHOT	Absolute path to a JSON snapshot of the project (the same data as moon project <id> --json), regenerated for each run.
MOON_TARGET	Fully-qualified target of the running task, e.g. app:build.
MOON_TASK_ID	ID of the running task.
MOON_TASK_HASH	The unique hash generated for the running task.
MOON_WORKSPACE_ROOT	Absolute path to the workspace root.
MOON_WORKING_DIR	Absolute path to the directory moon was invoked from.
PWD	Absolute path to the directory the task runs in — the project root, or the workspace root when runFromWorkspaceRoot is enabled.

note

Toolchains may inject additional variables (and prepend their binary directories to PATH) when setting up a task's environment. The variables above are always present regardless of toolchain.

During retries

When a task is retried (via retryCount), these are set for each attempt.

Variable	Description
MOON_TASK_RETRY_ATTEMPT	The current attempt number (starts at 1).
MOON_TASK_RETRY_TOTAL	The total number of attempts that will be tried.

Affected files

When a task configures affectedFiles to pass results through the environment, moon sets the following.

Variable	Description
MOON_AFFECTED_FILES	The list of affected files (relative to the working directory), joined by the OS path delimiter. May be . or empty when there are no matches, depending on configuration.

Terminal & color

When pipeline.inheritColorsForPipedTasks is enabled (the default), moon inherits the terminal's color support into piped task processes.

Variable	Description
FORCE_COLOR	Set to the detected color support level so child processes emit color.
CLICOLOR_FORCE	Same as FORCE_COLOR, for tools that follow the CLICOLOR convention.
COLUMNS	Forced to 80 so cached output is consistent across machines.
LINES	Forced to 24 so cached output is consistent across machines.

NO_COLOR is removed from the task environment when colors are being forced.

proto integration

Set on task processes and any proto/toolchain child processes that moon spawns.

Variable	Value	Description
PROTO_AUTO_INSTALL	false	Prevents proto from auto-installing tools during a task run.
PROTO_IGNORE_MIGRATE_WARNING	true	Silences proto migration warnings.
PROTO_NO_PROGRESS	true	Disables proto progress bars.
PROTO_VERSION	pinned	The proto version pinned in .moon/toolchains.yml.
STARBASE_FORCE_TTY	true	Forces TTY behavior for consistent output.

Internal

Set by moon for its own processes and integrations.

Variable	Description
MOON_VERSION	The currently running moon version.
MOON_DAEMON_RUNNING	Set to true inside the daemon server process.
MOON_VCS_REPO_SLUG	The detected owner/repository slug, derived from the VCS remote (only if not already set).

Variables moon reads

Global options

Each of these has an equivalent global command line option. The command line option takes precedence over the environment variable.

Variable	Option	Description
MOON_CACHE	--cache	Mode for cache operations: read, read-write (default), write, or off.
MOON_COLOR	--color	Force colored output.
MOON_CONCURRENCY	--concurrency	Maximum number of threads to utilize. Defaults to the number of CPU cores.
MOON_DUMP	--dump	Dump a trace profile to the working directory.
MOON_LOG	--log	Lowest log level to output: off, error, warn, info (default), debug, trace, verbose.
MOON_LOG_FILE	--log-file	Path to a file to write logs to.
MOON_QUIET	--quiet	Hide all moon console output.
MOON_THEME	--theme	Terminal theme to print with.

Running tasks & the pipeline

Read by moon exec, moon run, moon check, and moon ci. Most map to a command line option.

Variable	Option	Description
MOON_FORCE	--force	Force run and bypass cache, ignore changed files, and skip affected checks.
MOON_NO_ACTIONS	--no-actions	Run the pipeline without sync and setup related actions.
MOON_EXEC_PLAN	--plan	Relative path to an execution plan (JSON) that customizes the action graph.
MOON_SUMMARY	--summary	Print a summary of all actions that ran in the pipeline.
MOON_JOB	--job	Zero-based index of the current job (for CI job sharding).
MOON_JOB_TOTAL	--job-total	Total amount of jobs to run.
MOON_AFFECTED	--affected	Only run tasks affected by changed files.
MOON_BASE	--base	Base branch, commit, or revision to compare affected against.
MOON_HEAD	--head	Current branch, commit, or revision to compare with.
MOON_INCLUDE_RELATIONS	--include-relations	Include graph relations for affected checks, instead of just changed files.
MOON_ON_FAILURE	--on-failure	When a task fails, either bail the pipeline or continue executing.
MOON_OUTPUT_STYLE	—	The outputStyle task option in which output is printed.
MOON_RETRY_COUNT	—	The retryCount task option — number of times a failing task is retried.

Skipping actions

Skip individual pipeline actions. Set to true (or 1, *) to skip all, or provide a comma-separated list of project IDs / toolchain IDs / targets to skip only those that match.

Variable	Description
MOON_SKIP_SYNC_WORKSPACE	Skip the SyncWorkspace action.
MOON_SKIP_SYNC_PROJECT	Skip SyncProject actions (matches project IDs).
MOON_SKIP_SETUP_TOOLCHAIN	Skip SetupToolchain actions (matches toolchain IDs).
MOON_SKIP_SETUP_ENVIRONMENT	Skip SetupEnvironment actions (matches toolchain IDs).
MOON_SKIP_INSTALL_DEPS	Skip InstallDependencies actions (matches toolchain IDs).

Toolchain versions

MOON_<TOOLCHAIN>_VERSION overrides the version of a toolchain configured in .moon/toolchains.yml, where <TOOLCHAIN> is the uppercased toolchain ID. This is especially useful for testing against multiple versions in a CI matrix.

For example:

$ MOON_NODE_VERSION=20.0.0 moon run app:build
$ MOON_RUST_VERSION=1.90.0 moon run app:build

Configuration overrides

Override .moon/workspace.yml settings without editing the file.

Variable	Setting
MOON_DAEMON	daemon
MOON_TELEMETRY	telemetry
MOON_WEBHOOK_URL	notifier.webhookUrl
MOON_WEBHOOK_ACKNOWLEDGE	notifier.webhookAcknowledge
MOON_PIPELINE_AUTO_CLEAN_CACHE	pipeline.autoCleanCache
MOON_PIPELINE_CACHE_LIFETIME	pipeline.cacheLifetime
MOON_PIPELINE_KILL_PROCESS_THRESHOLD	pipeline.killProcessThreshold

Remote caching v1.30.0

Override remote settings for remote caching.

Variable	Setting / description
MOON_REMOTE_HOST	remote.host — gRPC host to connect to.
MOON_REMOTE_API	remote.api — API format of the remote service.
MOON_REMOTE_AUTH_TOKEN	remote.auth.token — name of the env var to use as a bearer token.
MOON_REMOTE_CACHE_*	Override remote.cache fields (e.g. MOON_REMOTE_CACHE_COMPRESSION, MOON_REMOTE_CACHE_INSTANCE_NAME).
MOON_REMOTE_TLS_HTTP2	remote.tls.assumeHttp2.
MOON_REMOTE_TLS_*	Override remote.tls fields.
MOON_REMOTE_MTLS_HTTP	remote.mtls.assumeHttp2.
MOON_REMOTE_MTLS_*	Override remote.mtls fields.

Experiments

Toggle experiments. Accepts a boolean-like value (true, 1, false, 0).

Variable	Setting
MOON_EXPERIMENT_ASYNC_AFFECTED_TRACKING	experiments.asyncAffectedTracking
MOON_EXPERIMENT_ASYNC_GRAPH_BUILDING	experiments.asyncGraphBuilding
MOON_EXPERIMENT_CAS_OUTPUTS_CACHE	experiments.casOutputsCache
MOON_EXPERIMENT_NATIVE_FILE_HASHING	experiments.nativeFileHashing

Debugging

Declare any of these (to a truthy value) to reveal additional diagnostic output. See debugging for more.

Variable	Description
MOON_DEBUG_PROCESS_ENV	Reveal the full environment passed to processes. By default moon hides everything except MOON_* variables to avoid leaking secrets.
MOON_DEBUG_PROCESS_INPUT	Reveal the full stdin passed to processes, instead of truncating it.
MOON_DEBUG_REMOTE	Extra logging for remote caching, including internal connection errors.
MOON_DEBUG_WASM	Extra logging for WASM plugins, and optionally dumps memory/core profiles.
MOON_DEBUG_DAEMON	Extra logging for the daemon.
MOON_DEBUG_MCP	Extra logging for the MCP server.

Graph visualizer

Read by the graph commands (project-graph, task-graph, action-graph) when starting the local visualization server.

Variable	Option	Description
MOON_HOST	--host	The host address to bind the server to. Defaults to 127.0.0.1.
MOON_PORT	--port	The port to bind to. Defaults to 0 (a random open port).
MOON_JS_URL	—	Override the URL of the visualizer JavaScript bundle (advanced).

Store & installation

Variable	Description
MOON_HOME	Override moon's store directory. Defaults to ~/.moon (or $XDG_DATA_HOME/moon when XDG_DATA_HOME is set).
MOON_INSTALL_DIR	Directory that moon upgrade installs the binary into. Defaults to ~/.moon/bin.

Advanced

Variable	Description
MOON_TOOLCHAIN_FORCE_GLOBALS	Force toolchains to use globally installed tools instead of proto-managed versions. Set automatically within Docker.
MOON_PLUGINS_USE_URL_DIST	Load plugins from their URL distribution instead of a locally built artifact.
MOON_VCS_REPO_SLUG	Override the detected owner/repository slug (see above).
MOON_TRACE_ID	A trace/correlation ID included in webhook payloads.

System variables

moon also inspects a number of standard, third-party variables to detect the current environment. These are read, never written.

Variable(s)	Purpose
CI, CI_NAME, AZURE_PIPELINES	Detect whether moon is running in a CI environment.
NO_COLOR, FORCE_COLOR, CLICOLOR, CLICOLOR_FORCE	Standard color output controls, honored and propagated.
XDG_DATA_HOME	Fallback location for moon's store directory.
SSH_CLIENT, SSH_TTY	Detect a remote SSH session.
CODESPACES, GITHUB_CODESPACES, GITPOD_INSTANCE_ID, DEVPOD, REPL_ID, and similar	Detect a cloud development environment ("devbox").
PATH	Resolve binaries, and the base that toolchains prepend their bin directories to.