Mesa CLI Reference

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.
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.

`mesa version`

Print the version of the Mesa CLI

mesa version [OPTIONS]

Options:

Flag	Short	Description
`--config-path <CONFIG_PATH>`	`-c`	Optional path to a Mesa config.toml file.
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.

`mesa stats`

Show statistics from a running Mesa daemon

mesa stats [OPTIONS]

Options:

Flag	Short	Description
`--config-path <CONFIG_PATH>`	`-c`	Optional path to a Mesa config.toml file.
`--format <FORMAT>`		Output format
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.
`--pid <PID>`		PID of the daemon to connect to
`--pid-file <PID_FILE>`		Path to the daemon’s PID file

`mesa show`

Show a revision’s description and patch against its parent

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.
`--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)
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.
`--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

`mesa root`

Show the current repository root directory

mesa root [OPTIONS]

Options:

Flag	Short	Description
`--config-path <CONFIG_PATH>`	`-c`	Optional path to a Mesa config.toml file.
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.

`mesa repo open`

Mount a repo so it shows up in the FUSE tree

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.
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.
`--org <ORG>`		Organization name. Inferred from cwd’s `user.mesa.org` xattr if omitted (only set on paths inside a mesa mount)
`--pid <PID>`		PID of the daemon to connect to
`--pid-file <PID_FILE>`		Path to the daemon’s PID file

`mesa repo list`

List mounted repos for an organization

mesa repo list [OPTIONS]

Options:

Flag	Short	Description
`--all`	`-a`	Fetch the full repo list from the API and show each repo’s mount status
`--config-path <CONFIG_PATH>`	`-c`	Optional path to a Mesa config.toml file.
`--format <FORMAT>`		Output format
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.
`--org <ORG>`		Organization name. Inferred from cwd’s `user.mesa.org` xattr if omitted (only set on paths inside a mesa mount)

`mesa repo create`

Create a new repository in an organization

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.
`--default-bookmark <DEFAULT_BOOKMARK>`		Default bookmark name (server defaults to “main” if omitted)
`--json`		Output the full API response as JSON
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.
`--org <ORG>`		Organization name. Inferred from cwd’s `user.mesa.org` xattr if omitted (only set on paths inside a mesa mount)
`--tag <TAGS>`		Tag in `key:value` format. Can be specified multiple times

`mesa repo close`

Unmount a repo so it no longer shows up in the FUSE tree

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.
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.
`--org <ORG>`		Organization name. Inferred from cwd’s `user.mesa.org` xattr if omitted (only set on paths inside a mesa mount)
`--pid <PID>`		PID of the daemon to connect to
`--pid-file <PID_FILE>`		Path to the daemon’s PID file

`mesa ping`

Ping a running Mesa daemon

mesa ping [OPTIONS]

Options:

Flag	Short	Description
`--config-path <CONFIG_PATH>`	`-c`	Optional path to a Mesa config.toml file.
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.
`--pid <PID>`		PID of the daemon to connect to
`--pid-file <PID_FILE>`		Path to the daemon’s PID file

`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

mesa org refresh [OPTIONS]

Options:

Flag	Short	Description
`--config-path <CONFIG_PATH>`	`-c`	Optional path to a Mesa config.toml file.
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.
`--org <ORG>`		Organization name. Inferred from cwd’s `user.mesa.org` xattr if omitted (only set on paths inside a mesa mount)
`--pid <PID>`		PID of the daemon to connect to
`--pid-file <PID_FILE>`		Path to the daemon’s PID file

`mesa new`

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

mesa new [OPTIONS] <BOOKMARK-OR-ID>

Arguments:

Argument	Description	Required
`BOOKMARK-OR-ID`	Bookmark name or change ID to base the new change on	Yes

Options:

Flag	Short	Description
`--config-path <CONFIG_PATH>`	`-c`	Optional path to a Mesa config.toml file.
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.
`--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

`mesa mount`

Mount the filesystem as a daemon process

mesa mount [OPTIONS]

Options:

Flag	Short	Description
`--config-path <CONFIG_PATH>`	`-c`	Optional path to a Mesa config.toml file.
`--daemonize`	`-d`	Run the daemon in the background
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.

`mesa log`

Show the commit log for the current repository

mesa log [OPTIONS]

Options:

Flag	Short	Description
`--config-path <CONFIG_PATH>`	`-c`	Optional path to a Mesa config.toml file.
`--limit <LIMIT>`	`-n`	Limit number of changes to show
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.
`--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). Defaults to the current checkout when inside a mesa mount

`mesa licenses`

List third-party dependency licenses

mesa licenses [OPTIONS]

Options:

Flag	Short	Description
`--config-path <CONFIG_PATH>`	`-c`	Optional path to a Mesa config.toml file.
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.

`mesa edit`

Switch to a different bookmark or change Aliases: checkout

mesa edit [OPTIONS] <BOOKMARK-OR-ID>

Arguments:

Argument	Description	Required
`BOOKMARK-OR-ID`	Bookmark name or change ID to switch to	Yes

Options:

Flag	Short	Description
`--config-path <CONFIG_PATH>`	`-c`	Optional path to a Mesa config.toml file.
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.
`--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

`mesa dump-default-mesaignore`

Print the default .mesaignore rules to stdout

mesa dump-default-mesaignore [OPTIONS]

Options:

Flag	Short	Description
`--config-path <CONFIG_PATH>`	`-c`	Optional path to a Mesa config.toml file.
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.

`mesa dump-config-template`

Print a documented Mesa config.toml template to stdout

mesa dump-config-template [OPTIONS]

Options:

Flag	Short	Description
`--config-path <CONFIG_PATH>`	`-c`	Optional path to a Mesa config.toml file.
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.

`mesa doctor`

Run health checks against the local mesa installation and config

mesa doctor [OPTIONS]

Options:

Flag	Short	Description
`--config-path <CONFIG_PATH>`	`-c`	Optional path to a Mesa config.toml file.
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.

`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

mesa describe [OPTIONS] [REVISION]

Arguments:

Argument	Description	Required
`REVISION`	Revision to describe — 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.
`--message <MESSAGE>`	`-m`	The new description/message for the change
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.
`--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

`mesa bookmark move`

Move an existing bookmark to point at a different change

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.
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.
`--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 the bookmark should point at. Accepts either an existing bookmark name or a raw change ID. Defaults to the current checkout when inside a mesa mount

`mesa bookmark list`

List bookmarks for a repository

mesa bookmark list [OPTIONS]

Options:

Flag	Short	Description
`--config-path <CONFIG_PATH>`	`-c`	Optional path to a Mesa config.toml file.
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.
`--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

`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

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.
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.
`--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. You can provide either an existing bookmark name or a raw change ID. If neither is found, this command errors

`mesa auth set-key`

Register an API key in the secret store. Scope is determined by flags: - --org <SLUG> --repo <NAME> → repo-scoped token - --org <SLUG> → org-scoped token - (no flags) → global fallback token The key value is read from the positional argument if supplied, otherwise from a single line on stdin.

mesa auth set-key [OPTIONS] <KEY>

Arguments:

Argument	Description	Required
`KEY`	API key value. Pass `-` to read from stdin	Yes

Options:

Flag	Short	Description
`--config-path <CONFIG_PATH>`	`-c`	Optional path to a Mesa config.toml file.
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.
`--org <ORG>`
`--repo <REPO>`

`mesa auth rm-key`

Remove an API key from the secret store

mesa auth rm-key [OPTIONS]

Options:

Flag	Short	Description
`--config-path <CONFIG_PATH>`	`-c`	Optional path to a Mesa config.toml file.
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.
`--org <ORG>`
`--repo <REPO>`

`mesa auth list-keys`

List all registered API keys (masked)

mesa auth list-keys [OPTIONS]

Options:

Flag	Short	Description
`--config-path <CONFIG_PATH>`	`-c`	Optional path to a Mesa config.toml file.
`--format <FORMAT>`
`--non-interactive`	`-y`	Skip interactive onboarding and generate config from defaults.

CLI

Documentation Index

​Global Options

​mesa version

​mesa stats

​mesa show

​mesa root

​mesa repo open

​mesa repo list

​mesa repo create

​mesa repo close

​mesa ping

​mesa org refresh

​mesa new

​mesa mount

​mesa log

​mesa licenses

​mesa edit

​mesa dump-default-mesaignore

​mesa dump-config-template

​mesa doctor

​mesa describe

​mesa bookmark move

​mesa bookmark list

​mesa bookmark create

​mesa auth set-key

​mesa auth rm-key

​mesa auth list-keys

Global Options

`mesa version`

`mesa stats`

`mesa show`

`mesa root`

`mesa repo open`

`mesa repo list`

`mesa repo create`

`mesa repo close`

`mesa ping`

`mesa org refresh`

`mesa new`

`mesa mount`

`mesa log`

`mesa licenses`

`mesa edit`

`mesa dump-default-mesaignore`

`mesa dump-config-template`

`mesa doctor`

`mesa describe`

`mesa bookmark move`

`mesa bookmark list`

`mesa bookmark create`

`mesa auth set-key`

`mesa auth rm-key`

`mesa auth list-keys`