Command Line Interface

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:

npm install -g mesa-cli

This makes the mesa command available from any directory.

Upgrading

To upgrade to the latest version:

npm install -g mesa-cli@latest

Authenticating

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

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:

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:

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:

mesa export my-automation-key

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

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:

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.

Troubleshooting

Could not find config.yml

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

Invalid token or 403 errors

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

No store selected during login

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.