---
title: Overview
---

import VersionLabel from '@site/src/components/Docs/VersionLabel';

The following options are available for _all_ moon commands.

- `--cache <mode>` - The mode for [cache operations](#caching).
- `--color` - Force [colored output](#colors) for moon (not tasks).
- `--concurrency`, `-c` - Maximum number of threads to utilize.
- `--dump` - Dump a [trace profile](#profiling) to the working directory.
- `--help` - Display the help menu for the current command.
- `--log <level>` - The lowest [log level to output](#logging).
- `--log-file <file>` - Write logs to the defined file.
- `--quiet`, `-q` - Hide all non-important moon specific terminal output.
- `--theme` - Terminal theme to write output in. <VersionLabel version="1.35.0" />
- `--version` - Display the version of the CLI.

## Caching

We provide a powerful [caching layer](../concepts/cache), but sometimes you need to debug failing or
broken tasks, and this cache may get in the way. To circumvent this, we support the `--cache` global
option, or the `MOON_CACHE` environment variable, both of which accept one of the following values.

- `off` - Turn off caching entirely. Every task will run fresh, including dependency installs.
- `read` - Read existing items from the cache, but do not write to them.
- `read-write` (default) - Read and write items to the cache.
- `write` - Do not read existing cache items, but write new items to the cache.

```shell
$ moon run app:build --cache off
# Or
$ MOON_CACHE=off moon run app:build
```

## Colors

Colored output is a complicated subject, with differing implementations and standards across tooling
and operating systems. moon aims to normalize this as much as possible, by doing the following:

- By default, moon colors are inherited from your terminal settings (`TERM` and `COLORTERM`
  environment variables).
- Colors can be force enabled by passing the `--color` option (preferred), or `MOON_COLOR` or
  `FORCE_COLOR` environment variables.

```shell
$ moon app:build --color run
# Or
$ MOON_COLOR=2 moon run app:build
```

When forcing colors with `MOON_COLOR` or `FORCE_COLOR`, you may set it to one of the following
numerical values for the desired level of color support. This is automatically inferred if you use
`--color`.

- `0` - No colors
- `1` - 16 colors (standard terminal colors)
- `2` - 256 colors
- `3` - 16 million colors (truecolor)

### Themes<VersionLabel version="1.35.0" />

By default, moon assumes a dark themed terminal is being used, and will output colors accordingly.
However, if you use a light theme, these colors are hard to read. To mitigate this, we support
changing the theme with the `--theme` global option, or the `MOON_THEME` environment variable.

```shell
$ moon run app:build --theme light
# Or
$ MOON_THEME=light moon run app:build
```

### Piped output

When tasks (child processes) are piped, colors and ANSI escape sequences are lost, since the target
is not a TTY and we do not implement a PTY. This is a common pattern this is quite annoying.
However, many tools and CLIs support a `--color` option to work around this limitation and to always
force colors, even when not a TTY.

To mitigate this problem as a whole, and to avoid requiring `--color` for every task, moon supports
the [`pipeline.inheritColorsForPipedTasks`](../config/workspace#inheritcolorsforpipedtasks)
configuration setting. When enabled, all piped child processes will inherit the color settings of
the currently running terminal.

## Concurrency

The `--concurrency` option or `MOON_CONCURRENCY` environment variable can be used to control the
maximum amount of threads to utilize in our thread pool. If not defined, defaults to the number of
operating system cores.

```shell
$ moon run app:build --concurrency 1
# Or
$ MOON_CONCURRENCY=1 moon run app:build
```

## Debugging

At minimum, most debugging can be done by passing [`--log debug`](#logging) on the command line and
sifting through the logs. We also provide the following environment variables to toggle output.

:::info

For a complete list of environment variables that moon sets and reads, see the
[environment variables](../env-vars) reference.

:::

- `MOON_DEBUG_PROCESS_ENV` - By default moon hides the environment variables (except for `MOON_`)
  passed to processes to avoid leaking sensitive information. However, knowing what environment
  variables are passed around is helpful in debugging. Declare this variable to reveal the entire
  environment.
- `MOON_DEBUG_PROCESS_INPUT` - By default moon truncates the stdin passed to processes to avoid
  thrashing the console with a large input string. However, knowing what input is passed around is
  helpful in debugging. Declare this variable to reveal the entire input.
- `MOON_DEBUG_PROTO_INSTALL` - Debug the proto installation process.
- `MOON_DEBUG_REMOTE` - Debug our remote caching implementation by including additional logging
  output, and printing internal connection errors.
- `MOON_DEBUG_WASM` - Debug our WASM plugins by including additional logging output, and optionally
  dumping memory/core profiles.

## Logging

By default, moon aims to output as little as possible, as we want to preserve the original output of
the command's being ran, excluding warnings and errors. This is managed through log levels, which
can be defined with the `--log` global option, or the `MOON_LOG` environment variable. The following
levels are supported, in priority order.

- `off` - Turn off logging entirely.
- `error` - Only show error logs.
- `warn` - Only show warning logs and above.
- `info` (default) - Only show info logs and above.
- `debug` - Only show debug logs and above. Recommended for most debugging, as it includes the
  majority of useful diagnostic information.
- `trace` - Show all logs, including network requests and child processes. As of v2.4 this is _very_
  verbose and is primarily intended for agents and deep diagnostics, and may be too spammy for
  normal debugging.
- `verbose` - Like `trace` but also includes span information. <VersionLabel version="1.35.0" />

```shell
$ moon run app:build --log trace
# Or
$ MOON_LOG=trace moon run app:build
```

### Writing logs to a file

moon can dump the logs from a command to a file using the `--logFile` option, or the `MOON_LOG_FILE`
environment variable. The dumped logs will respect the `--log` option and filter the logs piped to
the output file.

```shell
$ moon run app:build --logFile=output.log
# Or
$ MOON_LOG_FILE=output.log moon run app:build
```

## Profiling<VersionLabel version="1.26.0" />

When the `--dump` option or `MOON_DUMP` environment variable is set, moon will generate a trace
profile and dump it to the current working directory. This profile can be opened with Chrome (via
`chrome://tracing`) or [Perfetto](https://ui.perfetto.dev/).

This profile will display many of the operations within moon as a flame chart, allowing you to
inspect and debug slow operations.
