Every command. Every flag. Every exit code.
The full surface of arrow. Keep this open in a tab. The complete config schema is at the bottom.
Synopsis
arrow has a small set of top-level commands and a longer list of flags you can pass to any of them. There are no hidden subcommands and no interactive prompts - everything that takes input takes it from arrow.toml, an environment variable, or a flag.
arrow [global flags] <command> [args] [-- flags] # the most common shape, once you have an arrow.tomlarrow run build test bundle # quick one-off - no config neededarrow run -- node tests/smoke.mjs # introspectionarrow explain buildarrow doctorFlags on any command
These flags are accepted by every subcommand. Where a command treats a flag specially, it is called out in that command's section.
| Flag | Description |
|---|---|
| --config <path> | Path to arrow.toml (default: ./arrow.toml). |
| -C, --dir <path> | Change to <path> before reading the config. |
| --no-color | Disable ANSI styling in TTY output. |
| --json | Emit machine-readable JSON to stdout. |
| --quiet | Suppress step output, keep only pass/fail lines. |
| --verbose | Print each command-line before it runs. |
| --parallel <n> | Max concurrent jobs (default: max(2, ncpu)). |
| --remote-cache <url> | s3://… or file://… to share cache across hosts. |
init — Scaffold a project
Detect the project kind from existing files and write a starter arrow.toml. init never deletes files and never mutates anything other than the arrow.toml you point it at.
| Flag | Description |
|---|---|
| [path] | Directory to inspect (default: current directory). |
| -y, --yes | Skip the confirmation prompt in interactive use. |
| --kind <kind> | Force a project kind: web, lib, rust, mixed. |
| --force | Overwrite an existing arrow.toml without prompting. |
# let arrow figure it out$ arrow init # or pin a kind (useful in CI scaffolding)$ arrow init ./new-pkg --kind=lib --yes › writing arrow.toml› done in 0.3srun — Execute jobs
The workhorse. Run one or more named jobs from arrow.toml, ordered by dependency and parallelised where the graph allows. If you pass no names, arrow falls back to jobs.default if it exists, otherwise prints usage.
| Flag | Description |
|---|---|
| [job...] | One or more job names from [jobs.*] in arrow.toml. |
| --watch | Restart the affected jobs when files change. |
| --no-cache | Skip cache lookup; force every step to run. |
| --fail-fast | Abort siblings on first failure. |
| -- | If followed by a bare command, run it as an inline job. |
# run a specific job$ arrow run build # run several jobs in parallel$ arrow run build lint test --parallel=4 # run a one-off shell command (no arrow.toml needed)$ arrow run -- rg --files src/explain — Print the dependency graph
Prints the resolved DAG for one or more jobs as a tree, with cache keys annotated and the predicted critical path in seconds. Useful during code review.
| Flag | Description |
|---|---|
| --json | Emit the graph as a JSON object instead of a tree. |
| --dot | Emit Graphviz dot syntax for rendering. |
$ arrow explain test --json › {› "name": "test",› "edges": [["build", "vitest"], ["build", "report"]],› "cache_keys": ["a91f3c", "5d11a4", "78b32e"],› "critical_path_s": 9.6› }build — Run the canonical build job
A shorthand for arrow run default, or arrow run build when no default is defined. Most projects start here.
cache — Inspect and prune the local cache
The local cache lives in ~/.arrow/cache. Use arrow cache to inspect sizes, list entries, and prune old ones.
| Flag | Description |
|---|---|
| cache list | List cached keys, with size and last-used timestamps. |
| cache prune [--max-age <d>] | Drop entries older than <d> days (default: 30). |
| cache clear [--job <name>] | Drop everything, or only the entries for one job. |
$ arrow cache list › key size last-used job step› a91f3c 1.2 MB today build bundle› 5d11a4 312 KB today build lint› 78b32e 4.0 MB yesterday build bundle # drop everything older than 14 days$ arrow cache prune --max-age=14config — Read, write, and validate
Read and write arrow.toml from the command line, or validate it against the schema without running anything.
| Flag | Description |
|---|---|
| config get <key> | Print a config value, e.g. jobs.build.steps[0].run. |
| config set <key> <value> | Patch a value in place (preserves comments). |
| config check | Validate the file, exit 0 if it parses and resolves. |
| config format | Pretty-print the file with a stable canonical layout. |
doctor — Diagnose the install
Walk through the things arrow needs to run successfully - PATH entry, cache directory writability, config parser loaded, optional plugins detected - and print a friendly report.
| Flag | Description |
|---|---|
| --fix | Attempt to repair missing entries in $PATH (writes shell hints). |
| --json | Emit the report as JSON for downstream tools. |
self — Manage the binary itself
A small family of commands that act on the running arrow binary - update to a newer release, emit completions, or uninstall without a package manager.
| Flag | Description |
|---|---|
| self update [--channel stable|beta] | Download and replace the current binary. |
| self uninstall [--purge] | Remove the binary. --purge also drops the local cache. |
| self completions <shell> | Print a completion script. <shell> ∈ zsh, bash, fish, pwsh. |
| self info | Print the resolved install path, version, and build hash. |
plugins — Extend arrow with steps
A plugin is any executable on $PATH named arrow-NAME. arrow discovers them at startup and exposes them as step handlers by the same NAME.
| Flag | Description |
|---|---|
| plugins list | List discovered plugins with their versions. |
| plugins install <name> | Pull a plugin from the default registry. |
| plugins remove <name> | Remove a plugin from ~/.arrow/plugins. |
$ arrow plugins list › arrow-docker 0.2.1 /usr/local/bin/arrow-docker› arrow-ssh 0.1.4 ~/.arrow/plugins/arrow-ssh› arrow-rg 0.0.3 /opt/homebrew/bin/arrow-rgOnce installed, a plugin is referenced as a step type - for example: { name = "deploy", use = "ssh", target = "prod-01" }. See Getting Started for a worked example that adds a Docker step.
arrow.toml schema (v3)
The full shape of an arrow.toml file. Keys are stable - once a version is published it is additive-only, never renamed.
| Key | Type | Description |
|---|---|---|
| [project] | table | Required root. Project-wide metadata. |
| project.name | string | A short, human-readable name. |
| project.kind | enum | web | lib | rust | mixed | cli. |
| project.version | string | Semver. Used for cache partitioning. |
| [env] | table<string,string> | Environment variables exported to every step. |
| [jobs.<name>] | table | A named job. Names are restricted to [a-z0-9-_]. |
| jobs.<name>.description | string | Shown in arrow list and arrow explain. |
| jobs.<name>.depends | string[] | Other job names that must run first. |
| jobs.<name>.cache | glob | Outputs to keep in the cache for this job. |
| jobs.<name>.env | table<string,string> | Env vars added on top of [env]. |
| jobs.<name>.steps | step[] | Ordered list of steps to execute. |
| step | inline-table | A single unit of work. |
| step.name | string | Short label used in logs (required). |
| step.run | string | Shell command, executed with /bin/sh -c. |
| step.use | string | Plugin name, mutually exclusive with run. |
| step.input | string | Path passed to a plugin. |
| step.cache | glob | Outputs to keep in the cache for this step. |
| step.parallel | bool | Mark this step safe to run alongside siblings. |
| [plugins.<name>] | table | Optional pinned versions for plugins used by jobs. |