### Full actrun.toml Example

Source: https://github.com/mizchi/actrun/blob/main/docs/advanced-workflow.md

A comprehensive example of `actrun.toml` demonstrating workspace mode, skipping setup actions, trusting third-party actions, optional local context, Nix configuration, container runtime, and affected file patterns for workflows.

```toml
# Workspace
workspace_mode = "local"

# Skip setup actions — use local (or nix) toolchain
local_skip_actions = [
  "actions/checkout",
  "actions/setup-node",
  "actions/setup-python",
]

# Trust third-party actions
trust_actions = true

# Optional local GitHub context override
# [local_context]
# repository = "owner/repo"
# ref_name = "main"
# before_rev = "HEAD^"
# after_rev = "HEAD"
# actor = "your-name"

# Nix (auto-detected from flake.nix)
# nix_mode = ""
# nix_packages = ["python312", "jq"]

# Container runtime
# container_runtime = "docker"

# Affected file patterns per workflow
[affected."ci.yml"]
patterns = ["src/**", "package.json", "pnpm-lock.yaml"]

[affected."lint.yml"]
patterns = ["src/**", "*.config.*"]

[affected."docs.yml"]
patterns = ["docs/**", "*.md"]
```

--------------------------------

### Quick Start: Skip specific actions

Source: https://github.com/mizchi/actrun/blob/main/README.md

Run a workflow while skipping certain actions, useful for locally installed tools.

```bash
actrun workflow run .github/workflows/ci.yml \
  --skip-action actions/checkout \
  --skip-action extractions/setup-just
```

--------------------------------

### Quick Start: Generate config file

Source: https://github.com/mizchi/actrun/blob/main/README.md

Initialize an actrun.toml configuration file in the current directory.

```bash
actrun init
```

--------------------------------

### Install Actrun with moon

Source: https://github.com/mizchi/actrun/blob/main/README.md

Install Actrun using the moon package manager.

```bash
moon install mizchi/actrun/cmd/actrun
```

--------------------------------

### Actrun Configuration Example

Source: https://github.com/mizchi/actrun/blob/main/README.md

Example of an actrun.toml file showing various configuration options for workspace mode, skipping actions, trust settings, Nix integration, and more.

```toml
# Workspace mode: local, worktree, tmp, docker
workspace_mode = "local"

# Skip actions not needed locally
local_skip_actions = ["actions/checkout"]

# Trust all third-party actions without prompt
trust_actions = true

# Nix integration: "auto" (force), "off" (disable), or empty (auto-detect)
nix_mode = ""

# Additional nix packages
nix_packages = ["python312", "jq"]

# Container runtime: docker, podman, container, lima, nerdctl
container_runtime = "docker"

# Include uncommitted changes in worktree/tmp workspace
# include_dirty = true

# Default local GitHub context when `--event` is omitted
# [local_context]
# repository = "owner/repo"
# ref_name = "main"
# before_rev = "HEAD^"
# after_rev = "HEAD"
# actor = "your-name"

# Override actions with local commands
# [override."actions/setup-node"]
# run = "echo 'using local node' && node --version"

# Affected file patterns per workflow
# [affected."ci.yml"]
# patterns = ["src/**", "package.json"]

```

--------------------------------

### Clone Repository and Initial Setup

Source: https://github.com/mizchi/actrun/blob/main/CONTRIBUTING.md

Clone the actrun repository and run the default 'just' command for initial checks and tests.

```bash
git clone https://github.com/mizchi/actrun.git
cd actrun
just        # check + test
```

--------------------------------

### Install Actrun with Nix profile

Source: https://github.com/mizchi/actrun/blob/main/README.md

Install Actrun into your Nix profile for system-wide access.

```bash
nix profile install github:mizchi/actrun
```

--------------------------------

### Run Example Workflows

Source: https://github.com/mizchi/actrun/blob/main/CHEATSHEET.md

Execute various example workflows provided with actrun to test different features like environment variables, matrices, and secrets.

```bash
# Run example workflows
actrun workflow run examples/01-hello.yml
actrun workflow run examples/02-env-and-outputs.yml
actrun workflow run examples/03-matrix.yml
actrun workflow run examples/04-multi-job.yml
actrun workflow run examples/06-local-skip.yml
actrun workflow run examples/07-artifacts.yml
actrun workflow run examples/08-cache.yml
actrun workflow run examples/09-conditional.yml

# With secrets
ACTRUN_SECRET_API_TOKEN=test123 \
  actrun workflow run examples/05-secrets.yml
```

--------------------------------

### Install Actrun with curl

Source: https://github.com/mizchi/actrun/blob/main/README.md

Install Actrun on Linux or macOS using a curl script.

```bash
curl -fsSL https://raw.githubusercontent.com/mizchi/actrun/main/install.sh | sh
```

--------------------------------

### Quick Start: Show execution plan without running

Source: https://github.com/mizchi/actrun/blob/main/README.md

Display the planned execution steps of a workflow without actually running it.

```bash
actrun workflow run .github/workflows/ci.yml --dry-run
```

--------------------------------

### Quick Start: View results

Source: https://github.com/mizchi/actrun/blob/main/README.md

View the results of a previous run or logs for a specific task.

```bash
actrun run view run-1
actrun run logs run-1 --task build/test
```

--------------------------------

### Install Actrun globally with npm

Source: https://github.com/mizchi/actrun/blob/main/README.md

Install Actrun globally on your system using npm.

```bash
npm install -g @mizchi/actrun
```

--------------------------------

### Quick Start: Run a workflow locally

Source: https://github.com/mizchi/actrun/blob/main/README.md

Execute a GitHub Actions workflow file directly using Actrun.

```bash
actrun workflow run .github/workflows/ci.yml
```

--------------------------------

### Visualize Workflow Dependency Graph Example

Source: https://github.com/mizchi/actrun/blob/main/README.md

An example output showing the ASCII art representation of a workflow's job dependency graph.

```text
$ actrun viz .github/workflows/release.yml

┌───────┐    ┌────────┐
│ build │    │ docker │
└───────┘    └────────┘
    └┐
     │
┌─────────┐
│ release │
└─────────┘
```

--------------------------------

### Install Actrun with npx

Source: https://github.com/mizchi/actrun/blob/main/README.md

Run Actrun without a global installation using npx.

```bash
npx @mizchi/actrun workflow run .github/workflows/ci.yml
```

--------------------------------

### Actrun Configuration File

Source: https://github.com/mizchi/actrun/blob/main/docs/cheatsheet.md

Example `actrun.toml` file demonstrating configuration options for workspace mode, skipping actions, and trusting third-party actions.

```toml
# Workspace
workspace_mode = "local"

# Skip setup actions — use local toolchain
local_skip_actions = ["actions/checkout", "actions/setup-node"]

# Trust third-party actions
trust_actions = true
```

--------------------------------

### Quick Start: Run in isolated worktree

Source: https://github.com/mizchi/actrun/blob/main/README.md

Execute a workflow within an isolated worktree for cleaner execution.

```bash
actrun workflow run .github/workflows/ci.yml \
  --workspace-mode worktree
```

--------------------------------

### Run Actrun with Nix (no install)

Source: https://github.com/mizchi/actrun/blob/main/README.md

Execute Actrun directly using Nix without installing it globally.

```bash
nix run github:mizchi/actrun -- workflow run .github/workflows/ci.yml
```

--------------------------------

### Install Actrun with Docker

Source: https://github.com/mizchi/actrun/blob/main/README.md

Run Actrun using a Docker container, mounting the current directory as a workspace.

```bash
docker run --rm -v "$PWD":/workspace -w /workspace ghcr.io/mizchi/actrun workflow run .github/workflows/ci.yml
```

--------------------------------

### Check Dependencies

Source: https://github.com/mizchi/actrun/blob/main/docs/cheatsheet.md

Verify that all necessary dependencies for actrun are installed and configured correctly.

```bash
# Check dependencies
actrun doctor
```

--------------------------------

### Run a Workflow

Source: https://github.com/mizchi/actrun/blob/main/docs/cheatsheet.md

Execute a specified GitHub Actions workflow file. This is the most basic command to start a workflow run.

```bash
# Run a workflow
actrun .github/workflows/ci.yml

# Shorthand (same as above)
actrun workflow run .github/workflows/ci.yml
```

--------------------------------

### Matrix Strategy with Included Extra Key

Source: https://github.com/mizchi/actrun/blob/main/testdata/docs/strategy-matrix-include-extra-key/fixture.txt

This example demonstrates how to use the 'include' keyword in a GitHub Actions matrix to add an extra key ('version') to a specific combination of 'os' and 'node'. This allows for targeted job configurations.

```yaml
jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [12, 14]
        include:
          - os: ubuntu-latest
            node: 14
            version: 1.0
    steps:
      - uses: actions/setup-node@v1
        with:
          node-version: ${{ matrix.node }}
      - run: echo "Running on ${{ matrix.os }} with Node ${{ matrix.node }} and version ${{ matrix.version }}"
```

--------------------------------

### Example WASM CI Workflow

Source: https://github.com/mizchi/actrun/blob/main/docs/wasm-container.md

Demonstrates a CI workflow using the internal `wasm://` path for WASM actions. Includes steps for running tests and linters compiled to WASI, with shell scripting for reporting.

```yaml
name: wasm-ci
on: push
jobs:
  test:
    runs-on: ubuntu-latest
    env:
      ACTRUN_WASM_ACTION_ROOT: wasm-actions
    steps:
      - run: echo "starting WASM CI"

      # Run your test suite compiled to WASI
      - uses: wasm://my-tests@v1

      # Run linter compiled to WASI
      - uses: wasm://my-lint@v1
        with:
          config: .lintrc.toml

      # Shell glue for reporting
      - run: |
          if [ -f test-results.xml ]; then
            echo "Tests passed"
          fi

```

--------------------------------

### Matrix Strategy with Working Directory

Source: https://github.com/mizchi/actrun/blob/main/testdata/docs/strategy-matrix-working-directory/fixture.txt

Example of a matrix strategy where the 'working-directory' is set using a matrix variable. This is useful for running jobs in specific directories based on matrix configurations.

```yaml
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [14, 16]
    steps:
      - uses: actions/checkout@v3
      - name: Use Node.js ${{ matrix.node }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node }}
      - name: npm install, build, and test on ${{ matrix.os }}
        working-directory: ./my-package
        run: |
          npm install
          npm run build
          npm test
```

--------------------------------

### Configure Local Skip Actions

Source: https://github.com/mizchi/actrun/blob/main/docs/advanced-workflow.md

Specify actions to skip when running workflows locally, allowing the use of host-installed toolchains instead of GitHub Actions setup actions.

```toml
# Generated by: actrun init (auto-detects installed tools)
local_skip_actions = [
  "actions/checkout",
  "actions/setup-node",
  "actions/setup-python",
]
```

--------------------------------

### Skip Actions

Source: https://github.com/mizchi/actrun/blob/main/docs/cheatsheet.md

Prevent specific actions, like checkout or setup, from running. This is useful when using local tools instead of remote actions.

```bash
# Skip checkout and setup (use local tools)
actrun ci.yml --skip-action actions/checkout --skip-action actions/setup-node

# Or configure in actrun.toml:
#   local_skip_actions = ["actions/checkout", "actions/setup-node"]
actrun ci.yml
```

--------------------------------

### Matrix Job Name Substitution

Source: https://github.com/mizchi/actrun/blob/main/testdata/docs/strategy-matrix-job-name/fixture.txt

This example demonstrates how to use matrix variables to construct job names dynamically. It's useful for creating unique job identifiers based on the matrix configuration.

```yaml
name: Matrix job name substitution

on:
  push:

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [6, 16]
    steps:
      - name: Set up Node.js ${{ matrix.node }}
        uses: actions/setup-node@v1
        with:
          node-version: ${{ matrix.node }}
      - name: npm install
        run: npm install
      - name: npm test
        run: npm test
        env:
          OS_NAME: ${{ matrix.os }}

```

--------------------------------

### Quick Start: Emit flow cache plan JSON

Source: https://github.com/mizchi/actrun/blob/main/README.md

Generate a JSON representation of the flow cache plan for external orchestrators, including dry-run and specific flow signatures.

```bash
actrun workflow run .github/workflows/ci.yml \
  --dry-run \
  --json \
  --flow-cache-store /tmp/flow-cache.json \
  --flow-signature build=sig-build
```

--------------------------------

### Affected Run - First Execution

Source: https://github.com/mizchi/actrun/blob/main/docs/advanced-workflow.md

Example output for the first run of a workflow when `--affected` is used, as there is no previous successful run to compare against.

```bash
# First run (no history) always executes
$ actrun ci.yml --affected
affected: no previous successful run found, running
```

--------------------------------

### Skip GitHub Actions with Nix Integration

Source: https://github.com/mizchi/actrun/blob/main/docs/advanced-workflow.md

Configure `local_skip_actions` to prevent specific GitHub setup actions when using Nix for toolchains. `nix_mode` can be set to auto-detect `flake.nix`.

```toml
local_skip_actions = ["actions/checkout", "actions/setup-node"]
nix_mode = ""   # auto-detect flake.nix
```

--------------------------------

### Multiple Job Dependencies

Source: https://github.com/mizchi/actrun/blob/main/testdata/docs/jobs-needs/fixture.txt

This example shows 'job_3' depending on the successful completion of both 'job_1' and 'job_2'. This is useful for orchestrating workflows where multiple parallel tasks must finish before a consolidated task can begin.

```yaml
jobs:
  job_1:
    runs-on: ubuntu-latest
    steps:
      - run: echo "This is job 1"

  job_2:
    runs-on: ubuntu-latest
    steps:
      - run: echo "This is job 2"

  job_3:
    runs-on: ubuntu-latest
    needs: [job_1, job_2]
    steps:
      - run: echo "This is job 3, depends on job 1 and job 2"
```

--------------------------------

### Conditional Job Execution with `needs` and `if`

Source: https://github.com/mizchi/actrun/blob/main/testdata/docs/jobs-needs/fixture.txt

This example demonstrates how to conditionally run a job based on the success of a preceding job using `needs` and the `if` conditional. The `success()` function checks if all jobs listed in `needs` have succeeded.

```yaml
jobs:
  job_a:
    runs-on: ubuntu-latest
    steps:
      - run: exit 1 # This job will fail

  job_b:
    runs-on: ubuntu-latest
    needs: job_a
    if: success()
    steps:
      - run: echo "This job will not run because job_a failed"
```

--------------------------------

### Live Compatibility Testing - Step by Step

Source: https://github.com/mizchi/actrun/blob/main/README.md

Execute live compatibility tests in stages: dispatching the workflow, downloading the run artifact, and comparing the results.

```bash
just gha-compat-dispatch compat-checkout-artifact.yml
just gha-compat-download <run-id>
just gha-compat-compare compat-checkout-artifact.yml _build/gha-compat/<run-id>
```

--------------------------------

### Actrun Doctor Validation of Skipped Actions

Source: https://github.com/mizchi/actrun/blob/main/docs/advanced-workflow.md

Validates that skipped setup actions in `actrun.toml` have corresponding local tools installed. Shows which local tools were detected.

```bash
$ actrun doctor
...
=== actrun.toml ===
  local_skip_actions:
    - actions/checkout
    - actions/setup-node
    - actions/setup-python
ok  skip actions/setup-node: local node found (v24.12.0)
ok  skip actions/setup-python: local python3 found (Python 3.14.2)
```

--------------------------------

### Build Actrun from source

Source: https://github.com/mizchi/actrun/blob/main/README.md

Clone the repository, navigate to the directory, and build Actrun from source using moon.

```bash
git clone https://github.com/mizchi/actrun.git && cd actrun
moon build src/cmd/actrun --target native
```

--------------------------------

### Live Compatibility Testing - One-shot

Source: https://github.com/mizchi/actrun/blob/main/README.md

Perform a live compatibility test in a single command, including dispatching, waiting, downloading artifacts, and comparing results.

```bash
just gha-compat-live compat-checkout-artifact.yml
```

--------------------------------

### Nix: Build Actrun from source

Source: https://github.com/mizchi/actrun/blob/main/README.md

Build Actrun using Nix and then run the executable from the result path.

```bash
nix build github:mizchi/actrun
./result/bin/actrun workflow run .github/workflows/ci.yml
```

--------------------------------

### Affected Run - Changes Detected

Source: https://github.com/mizchi/actrun/blob/main/docs/advanced-workflow.md

Example output when changes are detected in relevant files, indicating that the workflow will proceed.

```bash
# After editing src/main.rs
$ actrun ci.yml --affected
affected: changes detected for ci.yml (since run-1)
run_id=run-2
...
```

--------------------------------

### Nix: Development shell with direnv

Source: https://github.com/mizchi/actrun/blob/main/README.md

Set up a development environment using Nix and direnv by creating an .envrc file.

```bash
echo "use flake" > .envrc
direnv allow
```

--------------------------------

### Quick Commands for MoonBit Project

Source: https://github.com/mizchi/actrun/blob/main/CLAUDE.md

Commonly used 'just' commands for managing a MoonBit project, including formatting, testing, and running the main application.

```bash
just           # check + test
just fmt       # format code
just check     # type check
just test      # run tests
just test-update  # update snapshot tests
just run       # run main
just info      # generate type definition files
```

--------------------------------

### JSON Output for Workflow Runs

Source: https://github.com/mizchi/actrun/blob/main/CHEATSHEET.md

Get workflow run information in JSON format, allowing selection of specific fields for programmatic use.

```bash
# JSON with field selection (like gh --json fields)
actrun run view run-1 --json status,conclusion,jobs
actrun run view run-1 --json workflowName,headBranch,startedAt
actrun run list --json status,conclusion --limit 5
```

--------------------------------

### Manage Cron Schedules

Source: https://github.com/mizchi/actrun/blob/main/docs/cheatsheet.md

Interact with cron schedule entries for workflows. This includes showing configured cron jobs, installing them to the system crontab, and uninstalling them.

```bash
# Show cron entries from workflow schedules
actrun cron show

# Install to system crontab
actrun cron install

# Remove actrun entries from crontab
actrun cron uninstall
```

--------------------------------

### Affected Run - No Changes Detected

Source: https://github.com/mizchi/actrun/blob/main/docs/advanced-workflow.md

Example output when no changes are detected in relevant files since the last successful run, causing the workflow to be skipped.

```bash
# No changes in src/ since last success
$ actrun ci.yml --affected
affected: no changes match patterns for ci.yml (since run-1)
```

--------------------------------

### Lint All Workflows

Source: https://github.com/mizchi/actrun/blob/main/docs/cheatsheet.md

Use this command to lint all YAML workflow files located in the .github/workflows/ directory. This is a good starting point for checking workflow syntax and configuration.

```bash
actrun lint
```

--------------------------------

### Generate Configuration

Source: https://github.com/mizchi/actrun/blob/main/docs/cheatsheet.md

Create a default `actrun.toml` configuration file. This command auto-detects local tools and generates a basic configuration structure.

```bash
# Generate config (auto-detects local tools)
actrun init
```

--------------------------------

### Build WASM from C

Source: https://github.com/mizchi/actrun/blob/main/examples/actions/hello-wasm/README.md

Build a C program using wasi-sdk to create a WebAssembly module and copy it to the Actrun WASM actions directory.

```bash
# Requires wasi-sdk
$WASI_SDK/bin/clang -o main.wasm main.c
cp main.wasm _build/actrun/wasm_actions/my-action/v1/main.wasm
```

--------------------------------

### Build WASM Actions (Go)

Source: https://github.com/mizchi/actrun/blob/main/docs/wasm-container.md

Compiles a Go project to WASI format and outputs the binary to the specified path for WASM actions.

```bash
# Go
GOOS=wasip1 GOARCH=wasm go build -o wasm-actions/my-tool/v1/main.wasm

```

--------------------------------

### Override Action with Custom Run Command

Source: https://github.com/mizchi/actrun/blob/main/README.md

Replace a specific 'uses:' action step with a custom 'run:' command defined in actrun.toml. This is useful for using locally installed tools.

```toml
[override."actions/setup-node"]
run = "echo 'using local node' && node --version"
```

--------------------------------

### Nix: Configuration without flakes

Source: https://github.com/mizchi/actrun/blob/main/README.md

Import Actrun directly from a tarball in your default.nix for use without flakes.

```nix
let
  actrun = import (builtins.fetchTarball "https://github.com/mizchi/actrun/archive/main.tar.gz") { };
in
  actrun
```

--------------------------------

### Build WASM from Go

Source: https://github.com/mizchi/actrun/blob/main/examples/actions/hello-wasm/README.md

Build a Go program for the WASI target and copy the compiled WebAssembly module to the Actrun WASM actions directory.

```bash
GOOS=wasip1 GOARCH=wasm go build -o main.wasm
cp main.wasm _build/actrun/wasm_actions/my-action/v1/main.wasm
```

--------------------------------

### Multiline Shell Commands in Run Step

Source: https://github.com/mizchi/actrun/blob/main/testdata/docs/steps-run/fixture.txt

Demonstrates how to execute multiple shell commands sequentially within a single 'run' step. This is useful for complex scripting tasks that require several commands to be executed in order.

```yaml
steps:
  - name: Setup environment
    run: |
      echo "Setting up environment..."
      mkdir -p build/logs
      echo "Environment setup complete."
```

--------------------------------

### Build WASM from WAT

Source: https://github.com/mizchi/actrun/blob/main/examples/actions/hello-wasm/README.md

Build a WebAssembly module directly from WebAssembly Text Format (WAT) and place it in the Actrun WASM actions directory.

```bash
# wasmtime can run .wat directly
cp main.wat _build/actrun/wasm_actions/hello/v1/main.wasm
```

--------------------------------

### MoonBit Project Structure Overview

Source: https://github.com/mizchi/actrun/blob/main/AGENTS.md

Lists the key files and their purposes within a MoonBit project, including module definitions, dependencies, source files, tests, and documentation files.

```text
- `moon.mod.json` - Module definition
- `moon.pkg` - Package dependencies (per directory)
- `*.mbt` - Source files
- `*_test.mbt` - Blackbox test files
- `*_wbtest.mbt` - Whitebox test files
- `*.mbt.md` - Doc test files
- `*.mbti` - Generated type interfaces (auto-generated by `moon info`)
```

--------------------------------

### Build WASM Actions (MoonBit)

Source: https://github.com/mizchi/actrun/blob/main/docs/wasm-container.md

Builds a MoonBit project for WASM and copies the compiled output to the designated WASM action path.

```bash
# MoonBit
moon build --target wasm
cp _build/wasm/release/build/my_tool.wasm wasm-actions/my-tool/v1/main.wasm

```

--------------------------------

### Using an action with inputs

Source: https://github.com/mizchi/actrun/blob/main/testdata/docs/steps-with/fixture.txt

This snippet shows how to use a pre-defined action within a workflow step and pass inputs to it. Ensure the action is available in your repository or the GitHub Marketplace.

```yaml
steps:
  - uses: actions/checkout@v3
  - name: Run a one-line script
    run: echo Hello, world!
  - name: Use an action with inputs
    uses: actions/setup-node@v3
    with:
      node-version: '16'
      registry-url: 'https://registry.npmjs.org'
```

--------------------------------

### Build WASM from MoonBit

Source: https://github.com/mizchi/actrun/blob/main/examples/actions/hello-wasm/README.md

Build a MoonBit project for the WebAssembly target and copy the compiled module to the Actrun WASM actions directory. It also shows how to run it with `moonrun`.

```bash
moon build --target wasm
cp _build/wasm/debug/build/<name>.wasm \
   _build/actrun/wasm_actions/my-action/v1/main.wasm
# Run with: ACTRUN_WASM_BIN=moonrun actrun workflow run ci.yml
```

--------------------------------

### Development Commands

Source: https://github.com/mizchi/actrun/blob/main/README.md

A set of `just` commands for common development tasks including formatting, type checking, testing, and end-to-end scenarios.

```bash
just              # check + test
just fmt          # format code
just check        # type check
just test         # run tests
just e2e          # run E2E scenarios
just release-check  # fmt + info + check + test + e2e
```

--------------------------------

### Nix: Add overlay to flake.nix

Source: https://github.com/mizchi/actrun/blob/main/README.md

Configure your Nix flake.nix to include Actrun as an overlay.

```nix
{ 
  inputs = { 
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
    actrun.url = "github:mizchi/actrun";
  };

  outputs = { nixpkgs, actrun, ... }:
    let
      system = "aarch64-darwin"; # or "x86_64-linux"
      pkgs = import nixpkgs { 
        inherit system;
        overlays = [ actrun.overlays.default ];
      };
    in
    {
      packages.${system}.default = pkgs.actrun;
      devShells.${system}.default = pkgs.mkShell { 
        packages = [ pkgs.actrun ];
      };
    };
}
```

--------------------------------

### Run a Workflow

Source: https://github.com/mizchi/actrun/blob/main/CHEATSHEET.md

Execute a GitHub Actions workflow file. Use `--dry-run` to preview the execution plan without making changes.

```bash
# Run a workflow
actrun workflow run .github/workflows/ci.yml

# Dry run (show plan, don't execute)
actrun workflow run .github/workflows/ci.yml --dry-run
```

--------------------------------

### View Run as JSON

Source: https://github.com/mizchi/actrun/blob/main/README.md

Displays the details of a specific run in JSON format.

```bash
actrun run view <run-id> --json      # View run as JSON
```

--------------------------------

### Build WASM Actions (C)

Source: https://github.com/mizchi/actrun/blob/main/docs/wasm-container.md

Compiles a C source file to WASI format using the wasi-sdk clang compiler and saves the output to the WASM action directory.

```bash
# C (wasi-sdk)
$WASI_SDK/bin/clang -o wasm-actions/my-tool/v1/main.wasm main.c

```

--------------------------------

### Execute Workflow with Nix Integration

Source: https://github.com/mizchi/actrun/blob/main/README.md

Run a workflow using actrun, automatically detecting and utilizing flake.nix or shell.nix for Nix-managed toolchains. Nix wrapping can be disabled or customized.

```bash
# Auto-detect flake.nix / shell.nix
actrun workflow run .github/workflows/ci.yml

# Disable nix wrapping
actrun workflow run .github/workflows/ci.yml --no-nix

# Ad-hoc packages without flake.nix
actrun workflow run .github/workflows/ci.yml --nix-packages "python312 jq"

# Disable via environment variable
ACTRUN_NIX=false actrun workflow run .github/workflows/ci.yml
```

--------------------------------

### Workspace Modes

Source: https://github.com/mizchi/actrun/blob/main/docs/cheatsheet.md

Select the environment for running workflows. Options include the current directory, an isolated git worktree, a temporary directory, or a Docker container.

```bash
# Run in current directory (default)
actrun ci.yml --local

# Isolated git worktree
actrun ci.yml --worktree

# Clone to temp directory
actrun ci.yml --tmp

# Run in Docker container
actrun ci.yml --workspace-mode docker
```

--------------------------------

### List Workflows

Source: https://github.com/mizchi/actrun/blob/main/README.md

Lists all workflows found in the .github/workflows/ directory.

```bash
actrun workflow list                 # List workflows in .github/workflows/
```

--------------------------------

### List Workflows

Source: https://github.com/mizchi/actrun/blob/main/docs/cheatsheet.md

Display all available workflows in the repository. You can also filter workflows using a glob pattern.

```bash
# List available workflows
actrun list

# List with custom glob
actrun list examples/*.yml
```

--------------------------------

### Download Artifacts

Source: https://github.com/mizchi/actrun/blob/main/CHEATSHEET.md

Download a specific artifact by name to a directory, or download all artifacts from a run to a specified directory.

```bash
# Download artifact
actrun artifact download run-1 --name report --dir ./out

# Download all artifacts
actrun run download run-1 --dir ./out
```

--------------------------------

### Nix: Development shell without direnv

Source: https://github.com/mizchi/actrun/blob/main/README.md

Enter the Nix development shell directly.

```bash
nix develop
```

--------------------------------

### View Workflow Run Summary and Details

Source: https://github.com/mizchi/actrun/blob/main/CHEATSHEET.md

Inspect a specific workflow run's summary, steps, or job details. Use `-v` to show verbose output for steps or filter by job.

```bash
# View run summary
actrun run view run-1
actrun run view run-1 -v              # show steps (like gh -v)
actrun run view run-1 --job build -v  # filter by job
```

--------------------------------

### Development Workflow Commands

Source: https://github.com/mizchi/actrun/blob/main/CONTRIBUTING.md

Common commands for development, including formatting, type checking, testing, and running the application.

```bash
just            # check + test
just fmt        # format code
just check      # type check (moon check --deny-warn)
just test       # run tests
just e2e        # run E2E scenarios
just run        # run main
```

--------------------------------

### Lint with a Specific Preset

Source: https://github.com/mizchi/actrun/blob/main/docs/cheatsheet.md

Apply a predefined linting configuration by using the --preset flag, choosing from 'default', 'strict', or 'oss'. This helps in standardizing linting across different projects or teams.

```bash
actrun lint --preset oss
```

--------------------------------

### Visualize Workflow as Themed SVG

Source: https://github.com/mizchi/actrun/blob/main/docs/cheatsheet.md

Create an SVG image of the workflow, applying a specific theme such as 'github-light'. This allows for visual consistency with platforms like GitHub.

```bash
actrun viz .github/workflows/ci.yml --svg --theme github-light
```

--------------------------------

### Actrun Lint Configuration

Source: https://github.com/mizchi/actrun/blob/main/README.md

Configures linting behavior, including presets and ignored rules, within the actrun.toml file.

```toml
[lint]
preset = "default"  # default, strict, oss
ignore_rules = ["unknown-property", "unused-outputs"]
```

--------------------------------

### Multiline Output with Heredoc

Source: https://github.com/mizchi/actrun/blob/main/testdata/docs/output-heredoc-special/fixture.txt

Demonstrates using a heredoc to capture multiline output, preserving special characters like backticks and dollar signs.

```bash
echo "```bash
echo 'hello world'
```" >> $GITHUB_OUTPUT
```

--------------------------------

### View Run Summary

Source: https://github.com/mizchi/actrun/blob/main/README.md

Displays a summary of a specific run identified by its ID.

```bash
actrun run view <run-id>             # View run summary
```

--------------------------------

### Download All Artifacts

Source: https://github.com/mizchi/actrun/blob/main/README.md

Downloads all artifacts associated with a completed run.

```bash
actrun run download <run-id>         # Download all artifacts
```

--------------------------------

### List Artifacts for a Run

Source: https://github.com/mizchi/actrun/blob/main/README.md

Lists all artifacts that were generated and stored for a specific run.

```bash
actrun artifact list <run-id>                          # List artifacts
```

--------------------------------

### Build WASM Actions (Rust)

Source: https://github.com/mizchi/actrun/blob/main/docs/wasm-container.md

Compiles a Rust project to WASI format and places the output in the expected directory structure for WASM actions.

```bash
# Rust
cargo build --target wasm32-wasip1 --release
cp target/wasm32-wasip1/release/my_tool.wasm wasm-actions/my-tool/v1/main.wasm

```

--------------------------------

### Full Release Check Command

Source: https://github.com/mizchi/actrun/blob/main/CONTRIBUTING.md

Run the 'just release-check' command to perform a comprehensive check including formatting, info, type checking, and end-to-end tests before submitting.

```bash
just release-check  # fmt + info + check + test + e2e
```

--------------------------------

### MoonBit Tooling Commands

Source: https://github.com/mizchi/actrun/blob/main/AGENTS.md

Lists essential `moon` commands for managing and developing MoonBit projects, such as formatting, interface generation, testing, and API discovery.

```bash
moon fmt - format code
moon info - update generated package interfaces (`.mbti`)
moon test - run tests. Use `moon test --update` to update snapshots.
moon check --deny-warn - type check with warnings as errors
moon doc '<query>' - discover APIs (more accurate than grep)
moon ide peek-def <Symbol> - show symbol definition
moon ide find-references <Symbol> - find all references
```

--------------------------------

### Visualize Workflow with Step-Level Detail

Source: https://github.com/mizchi/actrun/blob/main/docs/cheatsheet.md

Create a detailed Mermaid diagram that includes subgraphs for each step within the workflow jobs. This provides a granular view of the workflow's execution flow.

```bash
actrun viz .github/workflows/ci.yml --detail
```

--------------------------------

### Job Dependency with Outputs

Source: https://github.com/mizchi/actrun/blob/main/testdata/docs/jobs-needs/fixture.txt

This snippet illustrates how a job can depend on another and utilize its outputs. The `needs` keyword is used to establish the dependency, and the output from the preceding job is accessed using the `steps.<step_name>.outputs` context.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      my_output: ${{ steps.set_output.outputs.my_output }}
    steps:
      - id: set_output
        run: echo "my_output=hello" >> $GITHUB_OUTPUT

  test:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - run: echo "Output from build job: ${{ needs.build.outputs.my_output }}"
```

--------------------------------

### List Cache Entries

Source: https://github.com/mizchi/actrun/blob/main/README.md

Displays all currently stored cache entries.

```bash
actrun cache list                                      # List cache entries
```

--------------------------------

### Build WASM from Rust

Source: https://github.com/mizchi/actrun/blob/main/examples/actions/hello-wasm/README.md

Build a Rust project targeting WASI and copy the compiled WebAssembly module to the Actrun WASM actions directory.

```bash
cargo build --target wasm32-wasip1 --release
cp target/wasm32-wasip1/release/my_action.wasm \
   _build/actrun/wasm_actions/my-action/v1/main.wasm
```

--------------------------------

### Set Container Runtime for Actrun

Source: https://github.com/mizchi/actrun/blob/main/README.md

Configure the container runtime for job `container:`, `services:`, and `docker://` actions using a CLI flag, `actrun.toml`, or an environment variable.

```bash
# CLI flag
actrun workflow run ci.yml --container-runtime podman

# actrun.toml
container_runtime = "podman"

# Environment variable (also works)
ACTRUN_CONTAINER_RUNTIME=podman actrun workflow run ci.yml
```

--------------------------------

### Lint in Online Mode

Source: https://github.com/mizchi/actrun/blob/main/docs/cheatsheet.md

Use the --online flag to perform linting with network access. This allows actrun to verify the existence of actions and suggest pinning them to specific SHA references.

```bash
actrun lint --online
```

--------------------------------

### Provide Secrets and Variables

Source: https://github.com/mizchi/actrun/blob/main/docs/cheatsheet.md

Pass secrets and variables to workflows using environment variables or by loading them from a `.env` file. This is crucial for sensitive data and configuration.

```bash
# Provide secrets
ACTRUN_SECRET_MY_TOKEN=xxx actrun ci.yml

# Provide variables
ACTRUN_VAR_MY_VAR=value actrun ci.yml

# Load from .env file
actrun ci.yml --env .env.local
```

--------------------------------

### Download Artifacts

Source: https://github.com/mizchi/actrun/blob/main/docs/cheatsheet.md

Download artifacts generated by a specific workflow run. Artifacts are typically output files or build products.

```bash
# Download artifacts
actrun run download run-1
```

--------------------------------

### Debug a Real CI Workflow

Source: https://github.com/mizchi/actrun/blob/main/CHEATSHEET.md

A step-by-step process to debug a CI workflow locally using actrun, involving dry runs, execution, and log inspection.

```bash
# 1. See what would run
actrun workflow run .github/workflows/ci.yml \
  --skip-action actions/checkout \
  --skip-action extractions/setup-just \
  --dry-run

# 2. Run it
actrun workflow run .github/workflows/ci.yml \
  --skip-action actions/checkout \
  --skip-action extractions/setup-just

# 3. Check failures
actrun run logs run-1 --task test/step_3

# 4. Fix and re-run
actrun workflow run .github/workflows/ci.yml \
  --skip-action actions/checkout \
  --skip-action extractions/setup-just
```

--------------------------------

### Visualize Workflow Dependency Graph (ASCII)

Source: https://github.com/mizchi/actrun/blob/main/README.md

Renders the job dependency graph of a workflow in ASCII art format for terminal display.

```bash
actrun viz .github/workflows/ci.yml              # ASCII art (terminal)
```

--------------------------------

### Container Runtime Selection

Source: https://github.com/mizchi/actrun/blob/main/docs/cheatsheet.md

Specify the container runtime to use for workspace modes that require it. Supported runtimes include Docker, Podman, and Apple's Container runtime.

```bash
# Use podman instead of docker
actrun ci.yml --container-runtime podman

# Apple container runtime
actrun ci.yml --container-runtime container

# Lima (nerdctl via VM)
actrun ci.yml --container-runtime lima
```

--------------------------------

### Local GitHub Context

Source: https://github.com/mizchi/actrun/blob/main/docs/cheatsheet.md

Configure local context variables like repository, ref, and actor for deterministic runs. These values are typically auto-detected from the local git checkout but can be pinned in `actrun.toml`.

```bash
# Usually auto-detected from the local git checkout
actrun ci.yml

# Pin deterministic values in actrun.toml when needed
#   [local_context]
#   repository = "owner/repo"
#   ref_name = "feature/local-demo"
#   before_rev = "HEAD^"
#   after_rev = "HEAD"
#   actor = "your-name"
```

--------------------------------

### Build WASM Container Image

Source: https://github.com/mizchi/actrun/blob/main/docs/wasm-container.md

Builds the Docker image for the WASM container. Ensure you are in the directory containing the Dockerfile.

```bash
docker build -f Dockerfile.wasm -t actrun-wasm .

```

--------------------------------

### Basic Job Dependency with `needs`

Source: https://github.com/mizchi/actrun/blob/main/testdata/docs/jobs-needs/fixture.txt

This snippet demonstrates a simple dependency where 'job_2' runs only after 'job_1' has succeeded. Use this when a subsequent job requires the output or completion of a preceding job.

```yaml
jobs:
  job_1:
    runs-on: ubuntu-latest
    steps:
      - run: echo "This is job 1"

  job_2:
    runs-on: ubuntu-latest
    needs: job_1
    steps:
      - run: echo "This is job 2, depends on job 1"
```