# Workflow

> **Note (beta): mapbox workflow is in beta**
> 
> The `workflow` commands, the workflow format and the published workflows may change or be removed in any release. They're outside the CLI's [compatibility promise](https://docs.mapbox.com/cli/guides/#compatibility). Every `mapbox workflow` command says so on stderr.

A workflow is a named, multi-step recipe of `mapbox` commands and scripts, defined in a `workflow.yaml`. None ships inside the binary: `install` copies one into `~/.mapbox/workflows/<name>/`, and every other command works on what's installed there. Published workflows, and the format and rules a workflow directory follows, are in the [`workflow/` directory](https://github.com/mapbox/mapbox-cli/tree/main/workflow) of the Mapbox CLI repository.

**Only install a workflow you trust.** Its steps run as you, with your credentials and every stored profile, and a script step runs whatever its interpreter does. `install` lists the scripts a workflow runs, and asks before installing from a repository other than `mapbox/mapbox-cli` or from a `--ref` that isn't on that repository's `main` branch, such as a pull request. Only a typed `--yes` answers that question; `MAPBOX_YES` doesn't.

A script step needs its interpreter on `PATH`: `sh` for `.sh`, `python3` for `.py` and `node` for `.js`. Windows ships none of these, and the python.org installer adds `python` and `py` but not `python3`.

-   [`mapbox workflow list`](#mapbox-workflow-list)
-   [`mapbox workflow show`](#mapbox-workflow-show)
-   [`mapbox workflow install`](#mapbox-workflow-install)
-   [`mapbox workflow uninstall`](#mapbox-workflow-uninstall)
-   [`mapbox workflow run`](#mapbox-workflow-run)

## `mapbox workflow list`

Lists the installed workflows with their version and summary. One that no longer loads, because a file was edited by hand or this CLI no longer reads its format, is listed with its error instead of a summary.

**Examples:**

```sh
mapbox workflow list
mapbox workflow list -o json
```

## `mapbox workflow show`

Describes an installed workflow: its summary and description, its inputs with their types and defaults, its steps, and the installed copy's version, the oldest CLI it requires and where it came from. Script steps are marked as running as you. A step that names a command or argument this build no longer has is listed as a problem after the steps.

**Parameters:**

| Parameter | Description |
| --- | --- |
| `<NAME>` | Name of an installed workflow. |

**Examples:**

```sh
mapbox workflow show copy-style
```

## `mapbox workflow install`

Installs a workflow from GitHub or from a local directory. The CLI reads and checks everything before it writes anything: the layout, the `workflow.yaml`, and every command step against this build's commands. A workflow that fails any check, or that requires a newer CLI than this one, is refused with `invalid_workflow` and every problem listed at once.

The ref is resolved to one commit and read as one archive, and that commit is recorded and reported as `commit` by `install`, `list` and `show`. `mapbox/mapbox-cli` is public and needs no token. For a private repository, set `GH_TOKEN` or `GITHUB_TOKEN`; it's sent only to `api.github.com`.

An already-installed workflow stops the install unless you pass `--force`. A failed install leaves the old copy in place.

**Parameters:**

| Parameter | Description |
| --- | --- |
| `<SOURCE>` | A workflow name, looked up in the repository's `workflow/<name>/` directory, or a path to a local workflow directory (anything with a `/` or starting with `.`). |
| `--repo` | GitHub repository to install from, as `OWNER/REPO`. Defaults to `mapbox/mapbox-cli`. |
| `--ref` | Branch, tag or commit to install from. Defaults to `main`. A workflow release is tagged `workflow-<name>-<version>`. |
| `--force` | Replace a workflow that's already installed. |
| `--dry-run` | Check the workflow and list the files it would write, then exit. |

**Examples:**

```sh
mapbox workflow install copy-style
mapbox workflow install copy-style --ref workflow-copy-style-0.1.0
mapbox workflow install ./workflow/copy-style --force
GITHUB_TOKEN="$(gh auth token)" mapbox workflow install sync-tilesets --repo my-org/private-workflows
```

## `mapbox workflow uninstall`

Removes an installed workflow's directory. At a terminal it asks first; `--yes` answers in advance. Only a directory `install` wrote under `~/.mapbox/workflows/` is removed.

**Parameters:**

| Parameter | Description |
| --- | --- |
| `<NAME>` | Name of an installed workflow, or the local directory it was installed from (which names it by its directory name; that directory isn't touched). |
| `--dry-run` | Say what it would remove, then exit without removing it. |

**Examples:**

```sh
mapbox workflow uninstall copy-style
mapbox workflow uninstall copy-style --dry-run
```

## `mapbox workflow run`

Runs an installed workflow's steps in order. The first step that fails stops the run with `workflow_failed`, naming the step, and exit code 1.

Each input the workflow declares is a flag, spelled with dashes (`style_id` is `--style-id`), required, typed and defaulted as its `workflow.yaml` says. These flags aren't in `--schema` or shell completion; `mapbox workflow run <name> --help` or `mapbox workflow show <name>` lists them. A missing input, misspelled flag or wrongly typed value is a usage error (exit 2).

stdout holds only the result: the workflow's outputs, or the last step's output if it declares none. Each step's progress and anything a step writes to stderr go to stderr; `--quiet` keeps each step's title, how it ended and its warnings. Each command step is this binary run again with `--output json`, appears in [`mapbox history`](https://docs.mapbox.com/cli/reference/history/) as its own run, and inherits the global options given to `workflow run` (`--profile`, `--username`, `--use-login`, `--timeout`, `--yes`, `--debug`, `--token`) unless it sets its own.

`--dry-run` doesn't skip everything. Steps the workflow marks `dry_run` really run, so the plan can show what the rest would do with real data. A marked command step must be one the CLI knows changes nothing, but a marked script step runs as you, with your credentials, and only promises to write nothing — the CLI can't check that.

**Parameters:**

| Parameter | Description |
| --- | --- |
| `<NAME>` | Name of an installed workflow. |
| `--<input>` | One flag per input the workflow declares. |
| `--dry-run` | Check the workflow and its inputs and print the plan. Runs only the steps marked `dry_run`, script steps included, and skips the rest. |

**Examples:**

```sh
mapbox workflow run copy-style --help
mapbox workflow run copy-style \
  --style-id cmm28c5rm00bj01qz9hwp69qc \
  --from-profile source \
  --to-profile target
mapbox workflow run copy-style --style-id cmm28c5rm00bj01qz9hwp69qc \
  --from-profile source --to-profile target --dry-run
```