runn

Certain features in runn require explicit permission via scopes. You can specify these via the --scopes CLI flag, the RUNN_SCOPES environment variable, or the runn.Scopes() option in Go.

Available Scopes:

• read:parent: Required to read files above the current working directory.
• read:remote: Required to read remote files.
• run:exec: Required for using the Exec runner.

CLI Usage:

$ runn run path/to/**/*.yml --scopes read:parent,read:remote

Environment Variable:

$ env RUNN_SCOPES=read:parent,read:remote runn run path/to/**/*.yml

Go Usage:

o, err := runn.Load("path/to/**/*.yml", runn.Scopes(runn.AllowReadParent, runn.AllowReadRemote))

Disabling a scope: Use the ! prefix (e.g., --scopes '!read:parent').

To identify a specific step within a runbook (or a step within an included runbook), runn uses a URL query format appended to the Runbook ID.

Steps are indexed starting from 0. If a runbook includes another runbook, you can target a specific step in the parent and a specific step in the child using multiple step keys.

Format: [runbook ID]?step=[parent_step_index]&step=[child_step_index]

• The only allowed key is step.
• Multiple step keys are allowed and are processed in order.

Example: If you want to target step 2 of the main runbook, which is an Include runner pointing to step 0 of an included runbook, the identifier would be: [runbook ID]?step=2&step=0

In runn, there are two primary entities responsible for executing runbooks:

• runn.operator: Responsible for operating the execution of a single runbook.
• runn.operatorN: Responsible for operating multiple runbooks (multiple operators) together.

You can convert a single operator into an operatorN using the operator.toOperatorN method.

A runbook is the fundamental unit of execution in runn. When designing or writing runbooks, keep the following execution properties in mind:

• Sequential Execution: Steps within a runbook are always executed sequentially. runn does not assume or support concurrent running of steps within a single runbook.
• Lifecycle Management: When a runbook completes, all steps that have already started running will be stopped (for example, processes started via exec.background:).
• Deferred Steps: Steps marked with the defer: keyword do not start immediately. Instead, their execution is delayed until the parent runbook has completed its primary execution flow.

Object Expansion

When an object variable is used directly in headers: or body:, runn expands it as a map structure rather than a JSON string.

JSON Serialization

To force an object to be serialized into a JSON string (e.g., for a header value), wrap the template expression in single quotes.

vars:
  auth_headers:
    X-Token: xxx
    X-Api-Key: yyy
  metadata:
    user: alice
    role: admin

steps:
  - req:
      /api:
        get:
          # Expands as a map (multiple headers)
          headers: "{{vars.auth_headers}}"
          # Serializes to a JSON string
          headers:
            X-Metadata: "'{{vars.metadata}}'"

A runbook is a YAML file that defines a sequence of steps to execute. The steps: section can be defined as either a List (ordered) or a Map (named keys).

List Format

Steps are executed in order. Use index-based access to retrieve results from previous steps (e.g., {{ steps[0].rows[0].email }}).

Map Format

Steps are identified by unique keys. Use key-based access to retrieve results (e.g., {{ steps.find_user.rows[0].email }}).

# List format
steps:
  - db:
      query: SELECT * FROM users
  - req:
      /profile: 
        get:
          headers:
            id: "{{ steps[0].rows[0].id }}"

# Map format
steps:
  find_user:
    db:
      query: SELECT * FROM users
  get_profile:
    req:
      /profile:
        get:
          headers:
            id: "{{ steps.find_user.rows[0].id }}"

You can quickly generate runbook YAML files using the runn new command.

From a CLI command: Use runn new followed by --desc (description), --out (output file), and the command you want to wrap (e.g., curl or grpcurl). Adding the --and-run flag will execute the command immediately after creating the file.

From an access log: Pipe an access log directly into runn new --out <filename>.yml to automatically generate a scenario based on the requests found in the log.

# Create and run a scenario from a curl command
runn new --and-run --desc 'httpbin.org GET' --out http.yml -- curl https://httpbin.org/json -H "accept: application/json"

# Create a scenario from an access log
cat access_log | runn new --out axslog.yml

To record and save the results of runbook executions, use the --capture flag or the runn.Capture option.

Via CLI:

$ runn run path/to/**/*.yml --capture path/to/dir

Via Go API:

opts := []runn.Option{
	runn.T(t),
	runn.Capture(capture.Runbook("path/to/dir")),
}
o, err := runn.Load("testdata/books/**/*.yml", opts...)

CLI Installation

Homebrew (macOS/Linux):

$ brew install k1LoW/tap/runn

Go Install:

$ go install github.com/k1LoW/runn/cmd/runn@latest

Docker:

$ docker container run -it --rm --name runn -v $PWD:/books ghcr.io/k1low/runn:latest list /books/*.yml

Package Managers:

• deb: Download .deb from releases and use dpkg -i.
• RPM: Use yum install <url_to_rpm>.
• apk: Download .apk from releases and use apk add.
• aqua: aqua g -i k1LoW/runn

Go Library Installation

To use runn as a dependency in your Go projects:

$ go get github.com/k1LoW/runn