> For the complete documentation index, see [llms.txt](https://docs.getmesa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.getmesa.com/for-developers/command-line-interface.md).

# Command Line Interface

Install and upgrade the MESA CLI, then use it to manage workflows and scripts, run tests, view logs and activity, and download or publish changes.

Manage workflows and scripts, run tests, view logs and activity, and download, watch, and publish changes from the command line.

## Installing

Install the MESA CLI globally with npm:

```bash
npm install -g mesa-cli
```

This makes the `mesa` command available from any directory.

## Upgrading

To upgrade to the latest version:

```bash
npm install -g mesa-cli@latest
```

## Authenticating

Before you use the CLI, connect it to your MESA account:

```bash
mesa auth login
```

This opens your browser so you can authorize the CLI. If you have more than one MESA store, choose the store you want to connect. Once you approve, the CLI saves your credentials, including your API key, to `~/.mesa/config.yml`.

:::note
You don't need to find or copy an API key from the MESA dashboard. Running `mesa auth login` sets it for you.
:::

To check which account you're connected to, run `mesa auth status`. To clear your saved credentials, run `mesa auth logout`.

## Configuration

The CLI looks for a config file in these locations, in this order:

1. `./config/config.yml` (local, environment-specific)
2. `./config.yml` (local)
3. `~/.mesa/config/config.yml` (global, environment-specific)
4. `~/.mesa/config.yml` (global)

The config file uses this format. `mesa auth login` fills it in for you:

```yaml
uuid: your-mesa-uuid-here
key: your-api-key-here
api_url: https://api.getmesa.com/v1/admin  # optional
```

## Working with multiple stores

To switch between stores, save a separate config file for each one in a `./config/` folder, for example `./config/mystore.yml`. Then pass the file name with the `-e` flag or the `ENV` variable:

```bash
mesa -e mystore push
ENV=mystore mesa push
```

## Editing automations

To get started, export an automation. This downloads its `mesa.json` file and all of its scripts into the current directory:

```bash
mesa export my-automation-key
```

From that directory, use these commands to keep your local code in sync with MESA:

```bash
mesa pull                     # Download all scripts
mesa push *.js mesa.json      # Upload changes
mesa watch                    # Upload automatically as files change (Ctrl+C to stop)
```

You can pass specific files to `push` and `pull`, such as `mesa push script.js mesa.json`, or use a wildcard such as `*.js`.

## Commands reference

### Scripts and automations

| Command | What it does |
| --- | --- |
| `mesa push [files...]` | Upload scripts and configuration to MESA |
| `mesa pull [files...]` | Download scripts from MESA |
| `mesa watch` | Watch for file changes and upload them automatically |
| `mesa export <automation>` | Export an automation with all its scripts |
| `mesa install <template>` | Install a template from the MESA library. Add `-f` to force overwrite. |
| `mesa test <automation> [trigger]` | Test an automation. Add `-p '{"key": "value"}'` to send a payload. |
| `mesa replay <taskId>` | Replay a previously executed task |

### Workflows

| Command | What it does |
| --- | --- |
| `mesa workflow list` | List all workflows. Supports `--search`, `--limit`, `--page`, `--sort` (`name`, `updated_at`, `created_at`), `--sort-dir`, and `--json`. |
| `mesa workflow enable` | Enable a workflow. Run it alone to pick from a list, or pass `--workflow-id <id>`. |
| `mesa workflow disable` | Disable a workflow. Add `--yes` to skip the confirmation. |
| `mesa workflow test` | Run a full workflow test. Supports `--payload <path>`, `--default-payload`, `--non-interactive`, `--json`, and `--timeout <ms>` (default 300000). |
| `mesa workflow step test <workflowId>` | Run a step test. This currently runs the full workflow. Accepts the same options as `workflow test`. |
| `mesa workflow activity` | View recent runs. Filter with `--status` (`ready`, `running`, `success`, `fail`, `pause`, `skip`) or `--badge` (`test`, `replay`, `backfill`, `delayed`). |
| `mesa workflow debug enable\|disable\|status [workflowId]` | Turn debug logging on or off, or check which workflows have it on. |
| `mesa workflow time-travel` | Check status or start a backfill against historical data with `--from` and `--to` (YYYY-MM-DD) and `--limit`. |
| `mesa workflow create` | Build a workflow with an interactive wizard, or from JSON with `--non-interactive --input workflow.json`. Add `--push` to send it straight to MESA. |

:::caution
Debug logs only appear when both debug logging and logging are turned on for the workflow.
:::

### Logs

Run `mesa logs` to pick an automation from a searchable list. The list shows each automation's enabled status and last run time. You can also pass an automation ID directly:

```bash
mesa logs <automation-id> -n 10   # Last 10 logs for an automation
mesa logs -n 50                   # Last 50 logs across all automations
mesa logs -v                      # Include log metadata
```

### Authentication and cache

| Command | What it does |
| --- | --- |
| `mesa auth login` | Authorize the CLI in your browser |
| `mesa auth status` | Show your current authentication status |
| `mesa auth logout` | Clear stored credentials |
| `mesa cache clear` | Clear the local cache of trigger definitions and app configs |
| `mesa cache status` | Show the cache location and size |

### Global options

| Option | Description |
| --- | --- |
| `-e, --env <name>` | Config file to use |
| `-a, --automation <key>` | Automation key (overrides `mesa.json`) |
| `-f, --force` | Force overwrite |
| `-v, --verbose` | Verbose output |
| `-n, --number <n>` | Number of items |
| `-p, --payload <json>` | JSON payload for test or logs |

For the full JSON format and token syntax for `mesa workflow create`, see the [mesa-cli README](https://github.com/shoppad/mesa-cli).

## Troubleshooting

<details>

<summary>Could not find config.yml</summary>

Run `mesa auth login` to authenticate. This creates the config file for you.

</details>

<details>

<summary>Invalid token or 403 errors</summary>

Your API key may be expired or invalid. Run `mesa auth login` to re-authenticate.

</details>

<details>

<summary>No store selected during login</summary>

If you have more than one MESA store, the authorization page asks you to choose one. Select the store you want the CLI to connect to.

</details>