CLI triggers

A CLI trigger configures runs started from the CLI with rwx run by adding an on.cli block to your run definition. See Event Triggers for options shared across all trigger types, and Event Fields for the event fields available on CLI events.

Defining a CLI trigger

on:
  cli:
    init:
      commit-sha: ${{ event.git.sha }}

When you run rwx run .rwx/ci.yml, RWX will use the cli trigger configuration.

Testing workflows locally

You can start run definitions from the CLI without committing or pushing. rwx run picks up your local edits and applies them to the git/clone task, so you can iterate faster without having to push changes to a git remote.

Inside a git repository, rwx run finds the most recent commit in your branch's history that's already on your remote — the closest ancestor your local HEAD shares with origin, even if your branch itself has never been pushed — and uses that as the base for the run. event.git.sha resolves to that commit. The CLI then sends a patch on top covering everything from there to your working tree: local commits you haven't pushed, uncommitted edits, and new untracked files. With that patch applied, the git/clone task will match your local state.

Files ignored by your .gitignore are not included.

Event fields

The following fields are available on CLI events. They're derived from your local git state at the moment you run rwx run.

If RWX can't determine your local git state — for example, git isn't installed, you aren't inside a git repository, no remote is configured, or your branch shares no commits with the remote — event.git.* lookups fail with a descriptive error message naming the cause.

Best practices

Hard-coding init parameters

A common pattern is to hard-code certain init parameters in your CLI trigger to simplify local testing. For example:

on:
  github:
    push:
      init:
        commit-sha: ${{ event.git.sha }}
        environment: production
  cli:
    init:
      commit-sha: ${{ event.git.sha }}
      environment: development

In this example, runs triggered from the CLI will always use the development environment, while runs triggered from GitHub pushes will use production. This removes the need to pass --init environment=development every time you run from the CLI.

Targeting specific tasks

When testing locally, you often want to run a specific task rather than the entire workflow. Use the --target flag:

rwx run .rwx/ci.yml --target test

This runs only the test task and its dependencies, enabling faster iteration cycles.

CLI reference

For the full list of rwx run options, see the CLI reference. To find runs you've already started, list them with rwx runs list.