> ## 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 Reference

> Complete reference for all mesa commands, arguments, and options.

## Global Options

These flags are passed before any subcommand (e.g., `mesa --config-path <PATH> mount ...`).

| Flag                          | Short | Description                                                                         |
| ----------------------------- | ----- | ----------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables. |

***

## `mesa version`

Print the version of the Mesa CLI

```bash theme={null}
mesa version [OPTIONS]
```

**Options:**

| Flag                          | Short | Description                                                                         |
| ----------------------------- | ----- | ----------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables. |

***

## `mesa stats`

Show statistics from a running Mesa daemon

```bash theme={null}
mesa stats [OPTIONS]
```

**Options:**

| Flag                          | Short | Description                                                                         |
| ----------------------------- | ----- | ----------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables. |
| `--format <FORMAT>`           |       | Output format                                                                       |
| `--pid <PID>`                 |       | PID of the daemon to connect to                                                     |
| `--pid-file <PID_FILE>`       |       | Path to the daemon's PID file                                                       |

> `--pid-file` and `--pid` are mutually exclusive.

***

## `mesa show`

Show a revision's description and patch against its parent

```bash theme={null}
mesa show [OPTIONS] [REVISION]
```

**Arguments:**

| Argument   | Description                                                                           | Required |
| ---------- | ------------------------------------------------------------------------------------- | -------- |
| `REVISION` | Revision to show — bookmark name or change ID. Defaults to the current checkout (`@`) | No       |

**Options:**

| Flag                          | Short | Description                                                                                                                |
| ----------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables.                                        |
| `--git`                       |       | Show the patch in git unified-diff format. This is the default; the flag is accepted for `jj`-compatibility and is a no-op |
| `--name-only`                 |       | Print only the list of changed paths                                                                                       |
| `--no-patch`                  |       | Suppress the patch (header only)                                                                                           |
| `--pid <PID>`                 |       | PID of the daemon to connect to                                                                                            |
| `--pid-file <PID_FILE>`       |       | Path to the daemon's PID file                                                                                              |
| `--repo <ORG/REPO>`           |       | The repository in `org/repo` format. Auto-detected from CWD if omitted                                                     |
| `--stat`                      |       | Print a `+/-` histogram of changes per file (like `git diff --stat`)                                                       |
| `--summary`                   |       | Print a short per-file status line (A/M/D/R/C/T path) instead of a patch                                                   |

> `--pid-file` and `--pid` are mutually exclusive.

***

## `mesa root`

Show the current repository root directory

```bash theme={null}
mesa root [OPTIONS]
```

**Options:**

| Flag                          | Short | Description                                                                         |
| ----------------------------- | ----- | ----------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables. |

***

## `mesa repo open`

Deprecated no-op: all repos are always mounted

```bash theme={null}
mesa repo open [OPTIONS] <NAME>
```

**Arguments:**

| Argument | Description                     | Required |
| -------- | ------------------------------- | -------- |
| `NAME`   | Name of the repository to mount | Yes      |

**Options:**

| Flag                          | Short | Description                                                                         |
| ----------------------------- | ----- | ----------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables. |
| `--org <ORG>`                 |       | Organization name. Inferred from the current directory when run inside a mesa mount |
| `--pid <PID>`                 |       | PID of the daemon to connect to                                                     |
| `--pid-file <PID_FILE>`       |       | Path to the daemon's PID file                                                       |

> `--pid-file` and `--pid` are mutually exclusive.

***

## `mesa repo list`

List repos for an organization

```bash theme={null}
mesa repo list [OPTIONS]
```

**Options:**

| Flag                          | Short | Description                                                                         |
| ----------------------------- | ----- | ----------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables. |
| `--format <FORMAT>`           |       | Output format                                                                       |
| `--org <ORG>`                 |       | Organization name. Inferred from the current directory when run inside a mesa mount |

***

## `mesa repo create`

Create a new repository in an organization

```bash theme={null}
mesa repo create [OPTIONS] <NAME>
```

**Arguments:**

| Argument | Description                      | Required |
| -------- | -------------------------------- | -------- |
| `NAME`   | Name of the repository to create | Yes      |

**Options:**

| Flag                                    | Short | Description                                                                         |
| --------------------------------------- | ----- | ----------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>`           | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables. |
| `--default-bookmark <DEFAULT_BOOKMARK>` |       | Default bookmark name (server defaults to "main" if omitted)                        |
| `--json`                                |       | Output the full API response as JSON                                                |
| `--org <ORG>`                           |       | Organization name. Inferred from the current directory when run inside a mesa mount |
| `--tag <TAGS>`                          |       | Tag in `key:value` format. Can be specified multiple times                          |

***

## `mesa repo close`

Deprecated no-op: all repos are always mounted

```bash theme={null}
mesa repo close [OPTIONS] <NAME>
```

**Arguments:**

| Argument | Description                       | Required |
| -------- | --------------------------------- | -------- |
| `NAME`   | Name of the repository to unmount | Yes      |

**Options:**

| Flag                          | Short | Description                                                                         |
| ----------------------------- | ----- | ----------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables. |
| `--org <ORG>`                 |       | Organization name. Inferred from the current directory when run inside a mesa mount |
| `--pid <PID>`                 |       | PID of the daemon to connect to                                                     |
| `--pid-file <PID_FILE>`       |       | Path to the daemon's PID file                                                       |

> `--pid-file` and `--pid` are mutually exclusive.

***

## `mesa ping`

Ping a running Mesa daemon

```bash theme={null}
mesa ping [OPTIONS]
```

**Options:**

| Flag                          | Short | Description                                                                         |
| ----------------------------- | ----- | ----------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables. |
| `--pid <PID>`                 |       | PID of the daemon to connect to                                                     |
| `--pid-file <PID_FILE>`       |       | Path to the daemon's PID file                                                       |

> `--pid-file` and `--pid` are mutually exclusive.

***

## `mesa org refresh`

Drop the daemon's cached repo list for an org so the next lookup / readdir re-fetches from the backend. Useful after creating or deleting a repo via the REST API

```bash theme={null}
mesa org refresh [OPTIONS]
```

**Options:**

| Flag                          | Short | Description                                                                         |
| ----------------------------- | ----- | ----------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables. |
| `--org <ORG>`                 |       | Organization name. Inferred from the current directory when run inside a mesa mount |
| `--pid <PID>`                 |       | PID of the daemon to connect to                                                     |
| `--pid-file <PID_FILE>`       |       | Path to the daemon's PID file                                                       |

> `--pid-file` and `--pid` are mutually exclusive.

***

## `mesa new`

Create a new change on the current or specified bookmark / change

```bash theme={null}
mesa new [OPTIONS] <REVISION>
```

**Arguments:**

| Argument   | Description                                                 | Required |
| ---------- | ----------------------------------------------------------- | -------- |
| `REVISION` | Bookmark name or change ID prefix to base the new change on | Yes      |

**Options:**

| Flag                          | Short | Description                                                                         |
| ----------------------------- | ----- | ----------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables. |
| `--message <MESSAGE>`         | `-m`  | Description/message for the new change. Defaults to empty                           |
| `--pid <PID>`                 |       | PID of the daemon to connect to                                                     |
| `--pid-file <PID_FILE>`       |       | Path to the daemon's PID file                                                       |
| `--repo <ORG/REPO>`           |       | The repository in `org/repo` format. Auto-detected from CWD if omitted              |

> `--pid-file` and `--pid` are mutually exclusive.

***

## `mesa mount`

Mount the filesystem as a daemon process

```bash theme={null}
mesa mount [OPTIONS]
```

**Options:**

| Flag                          | Short | Description                                                                         |
| ----------------------------- | ----- | ----------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables. |
| `--daemonize`                 | `-d`  | Run the daemon in the background                                                    |

***

## `mesa log`

Show the commit log for the current repository

```bash theme={null}
mesa log [OPTIONS]
```

**Options:**

| Flag                          | Short | Description                                                                                                                       |
| ----------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables.                                               |
| `--limit <LIMIT>`             | `-n`  | Limit number of changes to show                                                                                                   |
| `--pid <PID>`                 |       | PID of the daemon to connect to                                                                                                   |
| `--pid-file <PID_FILE>`       |       | Path to the daemon's PID file                                                                                                     |
| `--repo <ORG/REPO>`           |       | The repository in `org/repo` format. Auto-detected from CWD if omitted                                                            |
| `--revision <REVISION>`       | `-r`  | Which revision to show history for (bookmark name or change ID prefix). Defaults to the current checkout when inside a mesa mount |

> `--pid-file` and `--pid` are mutually exclusive.

***

## `mesa edit`

Switch to a different bookmark or change

**Aliases:** `checkout`

```bash theme={null}
mesa edit [OPTIONS] <REVISION>
```

**Arguments:**

| Argument   | Description                                    | Required |
| ---------- | ---------------------------------------------- | -------- |
| `REVISION` | Bookmark name or change ID prefix to switch to | Yes      |

**Options:**

| Flag                          | Short | Description                                                                         |
| ----------------------------- | ----- | ----------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables. |
| `--pid <PID>`                 |       | PID of the daemon to connect to                                                     |
| `--pid-file <PID_FILE>`       |       | Path to the daemon's PID file                                                       |
| `--repo <ORG/REPO>`           |       | The repository in `org/repo` format. Auto-detected from CWD if omitted              |

> `--pid-file` and `--pid` are mutually exclusive.

***

## `mesa dump-default-mesaignore`

Print the default .mesaignore rules to stdout

```bash theme={null}
mesa dump-default-mesaignore [OPTIONS]
```

**Options:**

| Flag                          | Short | Description                                                                         |
| ----------------------------- | ----- | ----------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables. |

***

## `mesa dump-config-template`

Print a documented Mesa config.toml template to stdout

```bash theme={null}
mesa dump-config-template [OPTIONS]
```

**Options:**

| Flag                          | Short | Description                                                                         |
| ----------------------------- | ----- | ----------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables. |

***

## `mesa doctor`

Run health checks against the local mesa installation and config

```bash theme={null}
mesa doctor [OPTIONS]
```

**Options:**

| Flag                          | Short | Description                                                                         |
| ----------------------------- | ----- | ----------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables. |

***

## `mesa describe`

Update the description of a change. Defaults to the current checkout; pass a bookmark name or change ID to describe a different revision

```bash theme={null}
mesa describe [OPTIONS] [REVISION]
```

**Arguments:**

| Argument   | Description                                                                                | Required |
| ---------- | ------------------------------------------------------------------------------------------ | -------- |
| `REVISION` | Revision to describe — bookmark name or change ID prefix. Defaults to the current checkout | No       |

**Options:**

| Flag                          | Short | Description                                                                         |
| ----------------------------- | ----- | ----------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables. |
| `--message <MESSAGE>`         | `-m`  | The new description/message for the change                                          |
| `--pid <PID>`                 |       | PID of the daemon to connect to                                                     |
| `--pid-file <PID_FILE>`       |       | Path to the daemon's PID file                                                       |
| `--repo <ORG/REPO>`           |       | The repository in `org/repo` format. Auto-detected from CWD if omitted              |

> `--pid-file` and `--pid` are mutually exclusive.

***

## `mesa bookmark move`

Move an existing bookmark to point at a different change

```bash theme={null}
mesa bookmark move [OPTIONS] <NAME>
```

**Arguments:**

| Argument | Description                  | Required |
| -------- | ---------------------------- | -------- |
| `NAME`   | Name of the bookmark to move | Yes      |

**Options:**

| Flag                          | Short | Description                                                                                                    |
| ----------------------------- | ----- | -------------------------------------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables.                            |
| `--pid <PID>`                 |       | PID of the daemon to connect to                                                                                |
| `--pid-file <PID_FILE>`       |       | Path to the daemon's PID file                                                                                  |
| `--repo <ORG/REPO>`           |       | The repository in `org/repo` format. Auto-detected from CWD if omitted                                         |
| `--revision <REVISION>`       | `-r`  | Target revision — bookmark name or change ID prefix. Defaults to the current checkout when inside a mesa mount |

> `--pid-file` and `--pid` are mutually exclusive.

***

## `mesa bookmark list`

List bookmarks for a repository

```bash theme={null}
mesa bookmark list [OPTIONS]
```

**Options:**

| Flag                          | Short | Description                                                                         |
| ----------------------------- | ----- | ----------------------------------------------------------------------------------- |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables. |
| `--pid <PID>`                 |       | PID of the daemon to connect to                                                     |
| `--pid-file <PID_FILE>`       |       | Path to the daemon's PID file                                                       |
| `--repo <ORG/REPO>`           |       | The repository in `org/repo` format. Auto-detected from CWD if omitted              |

> `--pid-file` and `--pid` are mutually exclusive.

***

## `mesa bookmark create`

Create a new bookmark (a named pointer to a change). Points at the current change by default; use -r to point at a different change

```bash theme={null}
mesa bookmark create [OPTIONS] <NAME>
```

**Arguments:**

| Argument | Description                    | Required |
| -------- | ------------------------------ | -------- |
| `NAME`   | Name of the bookmark to create | Yes      |

**Options:**

| Flag                          | Short | Description                                                                                                                          |
| ----------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `--config-path <CONFIG_PATH>` | `-c`  | Optional path to a Mesa config.toml file. Deprecated: prefer environment variables.                                                  |
| `--pid <PID>`                 |       | PID of the daemon to connect to                                                                                                      |
| `--pid-file <PID_FILE>`       |       | Path to the daemon's PID file                                                                                                        |
| `--repo <ORG/REPO>`           |       | The repository in `org/repo` format. Auto-detected from CWD if omitted                                                               |
| `--revision <REVISION>`       | `-r`  | Specify which change the new bookmark should point to. Accepts a bookmark name or change ID prefix. Defaults to the current checkout |

> `--pid-file` and `--pid` are mutually exclusive.

***