> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Mesa CLI Configuration

> Environment variables and options for the Mesa CLI.

`mesa` is configured through environment variables. Config files are
deprecated and will stop being read in a future release — see
[Config file (deprecated)](#config-file-deprecated) below for migration.

## Required

| Variable       | Description                           |
| -------------- | ------------------------------------- |
| `MESA_API_KEY` | API key for authenticating with Mesa. |
| `MESA_ORG`     | Organization name to mount.           |

## Optional

| Variable                             | Description                                                                                                                          |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `MESA_MOUNT_POINT`                   | Path where repos are mounted (default: `~/.local/share/mesa/mnt`).                                                                   |
| `MESA_REPO_REVS`                     | Per-repo revision pins, comma-separated: `org/repo=bookmark:<name>` or `org/repo=change-id:<hex>`.                                   |
| `MESA_MESAIGNORE_PATH`               | Path to a global `.mesaignore` file. See [.mesaignore](/content/mesafs/advanced/mesaignore).                                         |
| `MESA_CACHE_ENABLED`                 | Enable the disk cache (`true`/`false`, default: `true`).                                                                             |
| `MESA_CACHE_MAX_SIZE`                | Maximum disk cache size (e.g. `1GB`).                                                                                                |
| `MESA_CACHE_MAX_MEMORY_SIZE`         | Maximum in-memory cache size (e.g. `256MB`).                                                                                         |
| `MESA_CACHE_PATH`                    | Path for the disk cache.                                                                                                             |
| `MESA_DAEMON_LOG_FILE`               | File path for daemon log output (default: stdout).                                                                                   |
| `MESA_DAEMON_LOG_COLOR`              | Log color mode: `auto`, `always`, or `never`.                                                                                        |
| `MESA_PREFETCH_ENABLED`              | Enable speculative prefetching (`true`/`false`).                                                                                     |
| `MESA_PREFETCH_MAX_DEPTH`            | Maximum directory depth the prefetcher walks.                                                                                        |
| `MESA_PREFETCH_MAX_CONCURRENCY`      | Maximum concurrent prefetch requests.                                                                                                |
| `MESA_PREFETCH_CACHE_PRESSURE_LIMIT` | Fraction of cache budget at which prefetching backs off (`0.0`–`1.0`).                                                               |
| `MESA_TELEMETRY`                     | Enable telemetry (`true`/`false`).                                                                                                   |
| `MESA_TELEMETRY_COLLECTOR_URL`       | OpenTelemetry collector URL for trace export.                                                                                        |
| `MESA_RUNTIME_DIR`                   | Directory for runtime state (PID file, RPC socket).                                                                                  |
| `MESA_NO_CONFIG_FILE`                | Skip reading any (deprecated) config file, even at a default search path. Recommended for sandboxes and other hermetic environments. |
| `MESA_SERVICE_DOMAIN`                | Custom service domain for self-hosted Mesa.                                                                                          |
| `MESA_UID` / `MESA_GID`              | POSIX owner of the mounted filesystem.                                                                                               |

## Daemon mode

Run `mesa mount` as a background daemon:

```bash theme={null}
mesa mount --daemonize
```

Log output goes to stdout by default. Redirect it to a file with
`MESA_DAEMON_LOG_FILE`:

```bash theme={null}
MESA_DAEMON_LOG_FILE=/var/log/mesa.log mesa mount --daemonize
```

## Ignore rules

Set `MESA_MESAIGNORE_PATH` to a `.mesaignore` file to control which files are
kept locally vs. uploaded to VCS. See
[.mesaignore](/content/mesafs/advanced/mesaignore) for details.

## Config file (deprecated)

<Warning>
  TOML config files (`config.toml` and `credentials.toml`) are deprecated and
  will stop being read in a future release. They are never created anymore.
  When one is loaded, `mesa` logs a warning for every setting it contains,
  naming the environment variable to use instead.
</Warning>

An existing config file is still honored, searched for in the following
locations (highest priority first), or at an explicit `--config-path`:

* `$XDG_CONFIG_HOME/mesa/config.toml` (Linux only)
* `$HOME/.config/mesa/config.toml`
* `/etc/mesa/config.toml`

Environment variables always take precedence over config file values.

Migrate each config key to its environment variable:

| Config key                                     | Environment variable                                                                                                 |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `[organizations.<org>]`                        | `MESA_ORG` (+ `MESA_API_KEY`)                                                                                        |
| `[organizations.<org>] mount = "explicit"`     | None — explicit mounting is removed; every repo the API key can access is mounted. Scope the key to restrict access. |
| `[organizations.<org>.repos.<repo>] rev = ...` | `MESA_REPO_REVS`                                                                                                     |
| `mount-point`                                  | `MESA_MOUNT_POINT`                                                                                                   |
| `service-domain`                               | `MESA_SERVICE_DOMAIN`                                                                                                |
| `uid` / `gid`                                  | `MESA_UID` / `MESA_GID`                                                                                              |
| `[cache] enabled`                              | `MESA_CACHE_ENABLED`                                                                                                 |
| `[cache] max-size`                             | `MESA_CACHE_MAX_SIZE`                                                                                                |
| `[cache] max-memory-size`                      | `MESA_CACHE_MAX_MEMORY_SIZE`                                                                                         |
| `[cache] path`                                 | `MESA_CACHE_PATH`                                                                                                    |
| `[daemon] pid-file`                            | `MESA_RUNTIME_DIR` (the PID file lives in the runtime directory)                                                     |
| `[daemon.log] target`                          | `MESA_DAEMON_LOG_FILE`                                                                                               |
| `[daemon.log] color`                           | `MESA_DAEMON_LOG_COLOR`                                                                                              |
| `[telemetry] vendor`                           | `MESA_TELEMETRY`                                                                                                     |
| `[telemetry] collector-url`                    | `MESA_TELEMETRY_COLLECTOR_URL`                                                                                       |
| `[prefetch] *`                                 | `MESA_PREFETCH_*`                                                                                                    |
| `credentials.toml` api keys                    | `MESA_API_KEY`                                                                                                       |
| `.mesaignore` next to `config.toml`            | `MESA_MESAIGNORE_PATH`                                                                                               |