CLI Triggers

RWX supports running workflows directly from the command line using rwx run. CLI triggers are defined in your run definition to configure how runs behave when started from the CLI.

For generic trigger options like title, target, if, and start, see Event Triggers.

Defining a CLI Trigger

Add a cli section under on in your run definition to configure CLI-triggered runs:

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

RWX supports and encourages testing run definitions directly from the CLI. You do not need to commit and push changes to test your workflows. This enables a fast iteration cycle when developing and debugging your CI/CD pipelines.

When you run rwx run, RWX automatically includes:

  1. Changes to run definitions in your definitions directory (usually .rwx/)
  2. Local changes to your code (if inside a git repository)

This means you can modify your workflow files and test them immediately without committing.

Local Code Changes

When run inside a git repository, rwx run includes local changes to your code via git patching. RWX does not include:

  • Changes ignored by your .gitignore settings
  • Changes to untracked files
  • Changes to git-lfs tracked files

You can disable git patching by setting the $RWX_DISABLE_GIT_PATCH environment variable.

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.