Skip to main content

The run Step

The run step allows you to execute arbitrary shell commands directly within your task. This allows you to integrate with existing command-line tools, scripts, or performing system-level operations that don't require the intelligence of an AI agent.

Key characteristics of a run step:

  • Direct Execution: The command specified in run is executed as if you were typing it into a terminal.
  • Output Capture: The standard output (stdout) of a run command can be captured and used as input for subsequent steps, often via the outputs.<step_index> variable.
  • Simplicity: Ideal for straightforward operations that don't require complex decision-making or code generation.

Examples from task​

Here are two examples of run steps from an example task:

1. Getting a list of files:

  - name: List project files
    run: ls -1 src/components/

In this example:

  • The run step executes the ls -1 src/components/ command, which lists all files in the src/components/ directory, one per line.
  • The output of this command (a list of file paths) can then be used by subsequent steps, such as a for_each loop.

2. Installing a command-line tool:

  - name: Install CLI tool
    run: npm install -g my-cli-tool@latest

In this example:

  • The run step executes an npm install command to install a generic command-line tool.
  • This ensures that my-cli-tool is available for use in later steps of the task, such as when an agent is instructed to use it for a specific task.

The run step provides a flexible way to incorporate any command-line operation into your Bosun tasks, bridging the gap between AI-driven automation and traditional scripting.

Working directory overrides​

Every manifest step accepts an optional working_directory. When you set it on a run step, the executor changes into that path before running the command, so shell operations that belong in nested packages stay scoped without extra cd logic.

steps:
  - name: Install frontend dependencies
    run: bun install --frozen-lockfile
    working_directory: apps/web

Bosun applies the same working directory to every tool the step invokes, so agent helpers, for_each iterations, and child shell commands inherit the directory as well. Leave the field unset to keep the workspace root, or set different directories on adjacent steps when your workflow jumps between packages. Use paths relative to the repository root so the executor stays inside the workspace.

Error handling​

By default a run step halts the task if the command fails. Set continue_on_error: true to record the failure and keep going—the runtime stores the error details in both the step output and the shared errors collection so later steps can inspect them. See Error handling for examples and templating tips.

Shell best practices
  • Use set -euo pipefail inside multi-line scripts to fail fast.
  • Print concise status messages so later steps can parse them from outputs.<step>.
  • Prefer JSON output when the data will feed another step; jq -c pairs well with Bosun templates.