exec Command

What It’s For

Run the same ad hoc command in every selected managed repository without writing a shell loop. aw exec is useful for repeated inspection, validation, tests, and maintenance commands across an Arashi workspace.

Each child command runs with its current working directory set to the selected repository path, not the meta-repo root.

Usage

aw exec [options] -- <command> [args...]

The -- delimiter is required before the child command. Arashi parses options before --; everything after -- is passed to the child command without being interpreted as Arashi options.

Options

• -o, --only <repos> run only named managed repositories; repeat it, use commas, or mix both forms.
• -g, --group <group> run only requested groups; repeat it, use commas, or mix both forms.
• --dirty run only in selected repositories that have local working-tree changes.
• --jobs <positive-int> remains long-only and runs up to that many repositories concurrently. The default is serial execution.
• --fail-fast stop scheduling additional repositories after the first child-command failure. Already-running jobs may finish and be reported.
• -j, --json emit one machine-readable JSON envelope instead of grouped human output.

Examples

# inspect all locally present managed repositories
aw exec -- git status --short

# validate one repository
aw exec --only arashi-docs -- pnpm validate

# validate all documentation repositories
aw exec --group docs -- pnpm validate

# inspect two repositories
aw exec --only arashi,arashi-docs -- git status --short

# show diffs only for repositories with local changes
aw exec --dirty -- git diff --stat

# run tests with bounded parallelism
aw exec --jobs 4 -- pnpm test

# stop starting new test jobs after the first failure
aw exec --jobs 4 --fail-fast -- pnpm test

# pass child-command flags after the delimiter
aw exec -- pnpm test -- --watch=false

# capture per-repository stdout, stderr, status, and totals for automation
aw exec --json -- git status --short

Output And Exit Behavior

Human output is grouped by repository so stdout, stderr, and failures remain attributable even when --jobs runs commands in parallel. The final summary reports successful, failed, and skipped or not-started repositories.

aw exec exits with status code 0 when every executed child command succeeds. If any executed child command exits non-zero, the Arashi process exits non-zero and identifies the failing repository or repositories.

When --dirty matches no repositories, aw exec exits successfully and reports that no dirty repositories matched.

JSON Mode

Use --json when automation needs to inspect results. JSON mode suppresses grouped human output and writes a single parseable document to stdout using the standard Arashi JSON envelope.

On full success, the result data includes the child command arguments, effective execution options, selected repositories, per-repository stdout and stderr, exit status, duration, and aggregate totals. If any selected repository fails, the JSON envelope uses ok: false and includes the same per-repository result details under the structured error details. The Arashi process exits non-zero when any selected repository fails.

Notes

• Use explicit filters for expensive or mutating commands. Prefer --group <group> for known semantic sets and --only <repo> for one-off repository lists.
• When combined with --only, --group narrows the explicit repository list by intersection.
• Prefer serial execution for commands that contend for shared resources or produce large output.
• --jobs <n> must be a positive integer.
• aw exec is intended for non-interactive fan-out commands; avoid child commands that require a TTY prompt or editor.
• Missing or unknown repositories named by --only are reported as errors instead of silently ignored.

Related

exec runs across configured repository selections and therefore requires configured mode. From standalone mode, run ordinary aw init to upgrade; see the Standalone Repository workflow.

• status for built-in workspace state inspection.
• setup for configured repository setup scripts.
• Agents workflow for automation guidance.