Workflow
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. 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
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 listmapbox workflow showmapbox workflow installmapbox workflow uninstallmapbox 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:
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:
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:
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:
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 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:
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