### WORKSPACE Setup (Legacy)

Source: https://context7.com/bazel-contrib/rules_multitool/llms.txt

For non-bzlmod projects, this macro in WORKSPACE.bazel sets up the hub repository and registers toolchains. After setup, call register_tools() to register all tool toolchains.

```python
# WORKSPACE.bazel
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "rules_multitool",
    sha256 = "<sha256>",
    urls = ["https://github.com/theoremlp/rules_multitool/releases/download/v0.12.0/rules_multitool-v0.12.0.tar.gz"],
)

load("@rules_multitool//multitool:multitool.bzl", "multitool")

multitool(
    name = "multitool",
    lockfile = "//:multitool.lock.json",
)

# Or use multiple lockfiles:
# multitool(
#     name = "multitool",
#     lockfiles = ["//:tools1.lock.json", "//:tools2.lock.json"],
# )

load("@multitool//:tools.bzl", "register_tools")

register_tools()

```

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

### Bazel Module Setup (bzlmod)

Source: https://context7.com/bazel-contrib/rules_multitool/llms.txt

Loads rules_multitool using a module extension in MODULE.bazel and creates a hub referencing a lockfile. This makes tool targets accessible via @multitool//tools/tool-name.

```python
# MODULE.bazel
bazel_dep(name = "rules_multitool", version = "0.12.0")

multitool = use_extension("@rules_multitool//multitool:extension.bzl", "multitool")
multitool.hub(lockfile = "//:multitool.lock.json")
use_repo(multitool, "multitool")

# Optional: Create an alternate named hub for grouping related tools
multitool.hub(
    hub_name = "alt_hub",
    lockfile = "//:other_tools.lock.json",
)
use_repo(multitool, "alt_hub")

# Register toolchains for alternate hub
register_toolchains("@alt_hub//toolchains:all")

```

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

### Run Tool from Command Line

Source: https://context7.com/bazel-contrib/rules_multitool/llms.txt

Execute tools directly using `bazel run`. By default, tools execute in the runfiles directory. Use the `:cwd` target suffix to run in the current working directory, or `:workspace_root` to run in the Bazel workspace root.

```bash
# Run a tool (executes in runfiles directory)
bazel run @multitool//tools/target-determinator

# Run a tool in the current working directory
bazel run @multitool//tools/target-determinator:cwd -- --help

# Run a tool in the workspace root directory
bazel run @multitool//tools/target-determinator:workspace_root -- --config=my-config.yaml

# Run the multitool CLI to update lockfile versions
bazel run @multitool//tools/multitool:cwd -- --lockfile ./multitool.lock.json update
```

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

### JSON Lockfile Configuration for Tools

Source: https://context7.com/bazel-contrib/rules_multitool/llms.txt

Defines platform-specific tool binaries, including their download URLs, SHA256 checksums, and archive extraction details. Supports 'file', 'archive', and 'pkg' kinds for different distribution formats.

```json
{
  "$schema": "https://raw.githubusercontent.com/theoremlp/rules_multitool/main/lockfile.schema.json",
  "target-determinator": {
    "binaries": [
      {
        "kind": "file",
        "url": "https://github.com/bazel-contrib/target-determinator/releases/download/v0.25.0/target-determinator.darwin.amd64",
        "sha256": "8c7245603dede429b978e214ca327c3f3d686a1bc712c1298fca0396a0f25f23",
        "os": "macos",
        "cpu": "x86_64"
      },
      {
        "kind": "file",
        "url": "https://github.com/bazel-contrib/target-determinator/releases/download/v0.25.0/target-determinator.linux.amd64",
        "sha256": "c8a09143e9fe6eccc4b27a6be92c5929e5a78034a8d0b4c43dbed4ee539ec903",
        "os": "linux",
        "cpu": "x86_64"
      }
    ]
  },
  "gh": {
    "binaries": [
      {
        "kind": "archive",
        "url": "https://github.com/cli/cli/releases/download/v2.44.1/gh_2.44.1_macOS_amd64.zip",
        "sha256": "1c545505b5b88feaffeba00b7284ccac3f2002b67461b1246eaec827eb07c31b",
        "file": "gh_2.44.1_macOS_amd64/bin/gh",
        "os": "macos",
        "cpu": "x86_64"
      },
      {
        "kind": "archive",
        "url": "https://github.com/cli/cli/releases/download/v2.44.1/gh_2.44.1_linux_amd64.tar.gz",
        "sha256": "f11eefb646768e3f53e2185f6d3b01b4cb02112c2c60e65a4b5875150287ff97",
        "file": "gh_2.44.1_linux_amd64/bin/gh",
        "os": "linux",
        "cpu": "x86_64"
      }
    ]
  },
  "aws": {
    "binaries": [
      {
        "kind": "pkg",
        "url": "https://awscli.amazonaws.com/AWSCLIV2-2.8.4.pkg",
        "sha256": "df0df526521a5b6c38b6954ec08c16453916daacca83582d37582654e9ca05a3",
        "file": "aws-cli.pkg/Payload/aws-cli/aws",
        "os": "macos",
        "cpu": "x86_64"
      }
    ]
  }
}
```

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

### Create and Use workspace_root Wrapper Rule

Source: https://context7.com/bazel-contrib/rules_multitool/llms.txt

The `workspace_root` rule creates a wrapper that executes a tool in the `BUILD_WORKSPACE_DIRECTORY`. This is useful for tools that need to operate on the entire project, such as linters or code generators that should always run from the workspace root.

```python
# BUILD.bazel
load(@rules_multitool//multitool:workspace_root.bzl, workspace_root)

# Create a workspace_root wrapper for a linter
workspace_root(
    name = "linter_workspace_root",
    tool = "@multitool//tools/my-linter",
)

# Use in tests
load(@rules_shell//shell:sh_test.bzl, sh_test)

sh_test(
    name = "lint_test",
    srcs = ["run_linter.sh"],
    args = [
        "$(location :linter_workspace_root)",
    ],
    data = [":linter_workspace_root"],
    env = {"BUILD_WORKSPACE_DIRECTORY": "."},
)
```

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

### Running Tools in Bazel Module/Workspace Root

Source: https://github.com/bazel-contrib/rules_multitool/blob/main/readme.md

Use the convenience target '@multitool//tools/[tool-name]:workspace_root' to run a tool in the Bazel module or workspace root.

```bash
@multitool//tools/[tool-name]:workspace_root
```

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

### Create and Use cwd Wrapper Rule

Source: https://context7.com/bazel-contrib/rules_multitool/llms.txt

The `cwd` rule creates a wrapper that executes a tool in the `BUILD_WORKING_DIRECTORY`. This is essential for tools that need to read or write files relative to the user's current directory. Import the rule and wrap any executable tool.

```python
# BUILD.bazel
load(@rules_multitool//multitool:cwd.bzl, cwd)

# Create a cwd wrapper for a custom tool
cwd(
    name = "my_formatter_cwd",
    tool = "@multitool//tools/my-formatter",
)

# Use in tests with explicit BUILD_WORKING_DIRECTORY
load(@rules_shell//shell:sh_test.bzl, sh_test)

sh_test(
    name = "formatter_test",
    srcs = ["test_formatter.sh"],
    args = [
        "$(location :my_formatter_cwd)",
    ],
    data = [":my_formatter_formatter_cwd"],
    env = {"BUILD_WORKING_DIRECTORY": "."},
)
```

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

### Running Tools in Current Working Directory

Source: https://github.com/bazel-contrib/rules_multitool/blob/main/readme.md

Workaround for Bazel executing tools at the root of the runfiles tree. Use convenience targets like '@multitool//tools/[tool-name]:cwd' to run a tool in the current working directory.

```bash
@multitool//tools/[tool-name]:cwd
```

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

### Define Tool Lockfile Structure

Source: https://github.com/bazel-contrib/rules_multitool/blob/main/readme.md

Define a lockfile that references the tools to load. Supports 'file', 'archive', and 'pkg' binary kinds with various download and authentication options.

```json
{
  "$schema": "https://raw.githubusercontent.com/theoremlp/rules_multitool/main/lockfile.schema.json",
  "tool-name": {
    "binaries": [
      {
        "kind": "file",
        "url": "https://...",
        "sha256": "sha256 of the file",
        "os": "linux|macos|windows",
        "cpu": "x86_64|arm64"
      }
    ]
  }
}
```

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

### Lockfile Binary Types Configuration

Source: https://context7.com/bazel-contrib/rules_multitool/llms.txt

The lockfile supports three binary kinds: `file` for direct executable downloads, `archive` for compressed archives, and `pkg` for macOS package files. All types support optional `headers` and `auth_patterns` for authenticated downloads.

```json
{
  "$schema": "https://raw.githubusercontent.com/theoremlp/rules_multitool/main/lockfile.schema.json",
  "direct-download-tool": {
    "binaries": [
      {
        "kind": "file",
        "url": "https://example.com/tool-linux-amd64",
        "sha256": "abc123...",
        "os": "linux",
        "cpu": "x86_64",
        "headers": {
          "Authorization": "Bearer ${TOKEN}"
        },
        "auth_patterns": {
          "example.com": "Bearer <password>"
        }
      }
    ]
  },
  "archived-tool": {
    "binaries": [
      {
        "kind": "archive",
        "url": "https://example.com/tool-v1.0.0.tar.gz",
        "sha256": "def456...",
        "file": "tool-v1.0.0/bin/tool",
        "type": "tar.gz",
        "os": "linux",
        "cpu": "x86_64"
      },
      {
        "kind": "archive",
        "url": "https://example.com/tool-v1.0.0.zip",
        "sha256": "ghi789...",
        "file": "tool-v1.0.0/bin/tool.exe",
        "type": "zip",
        "os": "windows",
        "cpu": "x86_64"
      }
    ]
  },
  "macos-pkg-tool": {
    "binaries": [
      {
        "kind": "pkg",
        "url": "https://example.com/tool.pkg",
        "sha256": "jkl012...",
        "file": "tool.pkg/Payload/usr/local/bin/tool",
        "os": "macos",
        "cpu": "arm64"
      }
    ]
  }
}
```

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

### Use Tool as Data Dependency in BUILD File

Source: https://context7.com/bazel-contrib/rules_multitool/llms.txt

Reference tools via the hub repository at `@multitool//tools/tool-name`. Tools automatically resolve to the correct platform variant. Use tools as data dependencies in tests or as executable targets.

```python
# BUILD.bazel
load(@rules_shell//shell:sh_test.bzl, sh_test)

# Use a tool as a data dependency in a test
sh_test(
    name = "integration_test",
    srcs = ["integration_test.sh"],
    args = [
        "$(location @multitool//tools/target-determinator)",
    ],
    data = ["@multitool//tools/target-determinator"],
)

# Use a tool from an alternate hub
sh_test(
    name = "alt_hub_test",
    srcs = ["test.sh"],
    args = [
        "$(location @alt_hub//tools/gh)",
    ],
    data = ["@alt_hub//tools/gh"],
)
```

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

### GitHub Action for Multitool Updates via Direct CLI

Source: https://github.com/bazel-contrib/rules_multitool/blob/main/docs/automation.md

This workflow automates multitool version updates by downloading and executing the multitool CLI directly. It requires a GitHub App for authentication and checks out the repository. Changes are committed and a pull request is created if modifications are detected.

```yaml
name: Periodic - Update Multitool Versions
on:
  workflow_dispatch: {}
  schedule:
    # run every hour on the 5 between 9am and 5pm (4am and 12pm UTC), M-F
    - cron: "5 14-22 * * 1-5"
jobs:
  update-requirement:
    name: Update Multitool Versions
    runs-on: ubuntu-latest
    permissions:
      contents: read
    # disable running on anything but main
    if: ${{ github.ref == 'refs/heads/main' }}
    env:
      LOCKFILE: ./multitool.lock.json
    steps:
      - name: Get Token
        id: app-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ secrets.AUTOMATION_APP_ID }}
          private-key: ${{ secrets.AUTOMATION_PRIVATE_KEY }}
      - uses: actions/checkout@v4
        with:
          token: ${{ steps.app-token.outputs.token }}
      - name: Download and Extract Latest Multitool
        run: wget -O- https://github.com/theoremlp/multitool/releases/latest/download/multitool-x86_64-unknown-linux-gnu.tar.xz | tar --strip-components=1 -xJf -

      - name: Find Updates and Render Lockfile
        run: ./multitool --lockfile "$LOCKFILE" update

      - name: Commit Changes
        env:
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          BRANCH_NAME: "automation/update-multitool-lockfile"
        run: |
          if [[ -n "$(git diff "$LOCKFILE")" ]]
          then
            git config --local user.name 'Automation'
            git config --local user.email 'app-name[bot]@users.noreply.github.com'
            git checkout -b "${BRANCH_NAME}"
            git add "$LOCKFILE"
            git commit -m "Update Multitool Versions
            
            Updated with [update-multitool](${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}) by *${GITHUB_ACTOR}*
            "
            git push origin "${BRANCH_NAME}" -f
            gh pr create --fill --label "automerge" >> "$GITHUB_STEP_SUMMARY"
          fi
```

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

### Bazel Module Usage: Load rules_multitool

Source: https://github.com/bazel-contrib/rules_multitool/blob/main/readme.md

Load the rules_multitool ruleset in your MODULE.bazel and create a hub that refers to your lockfile. Tools can then be accessed using the defined hub.

```python
bazel_dep(name = "rules_multitool", version = "0.0.0")

multitool = use_extension("@rules_multitool//multitool:extension.bzl", "multitool")
multitool.hub(lockfile = "//:multitool.lock.json")
use_repo(multitool, "multitool")
```

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

### Configure GitHub Action for Automatic Tool Updates

Source: https://context7.com/bazel-contrib/rules_multitool/llms.txt

This GitHub Actions workflow automates the process of checking for and applying updates to multitool versions in the lockfile. It requires a GitHub App for authentication and is scheduled to run periodically.

```yaml
# .github/workflows/update-multitool.yml
name: Periodic - Update Multitool Versions
on:
  workflow_dispatch: {}
  schedule:
    - cron: "5 14-22 * * 1-5"  # Hourly 9am-5pm UTC, M-F
jobs:
  update-requirement:
    name: Update Multitool Versions
    runs-on: ubuntu-latest
    permissions:
      contents: read
    if: ${{ github.ref == 'refs/heads/main' }}
    env:
      LOCKFILE: ./multitool.lock.json
    steps:
      - name: Get Token
        id: app-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ secrets.AUTOMATION_APP_ID }}
          private-key: ${{ secrets.AUTOMATION_PRIVATE_KEY }}
      - uses: actions/checkout@v4
        with:
          token: ${{ steps.app-token.outputs.token }}

      - name: Find Updates and Render Lockfile
        run: bazel run @multitool//tools/multitool:cwd -- --lockfile "$LOCKFILE" update

      - name: Commit Changes
        env:
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          BRANCH_NAME: "automation/update-multitool-lockfile"
        run: |
          if [[ -n "$(git diff "$LOCKFILE")" ]]
          then
            git config --local user.name 'Automation'
            git config --local user.email 'automation[bot]@users.noreply.github.com'
            git checkout -b "${BRANCH_NAME}"
            git add "$LOCKFILE"
            git commit -m "Update Multitool Versions"
            git push origin "${BRANCH_NAME}" -f
            gh pr create --fill --label "automerge" >> "$GITHUB_STEP_SUMMARY"
          fi

```

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

### GitHub Action for Multitool Updates via rules_multitool

Source: https://github.com/bazel-contrib/rules_multitool/blob/main/docs/automation.md

This workflow automates multitool version updates by using the rules_multitool Bazel rule. It requires a GitHub App for authentication and checks out the repository before running the update command. Changes are committed and a pull request is created if modifications are detected.

```yaml
name: Periodic - Update Multitool Versions
on:
  workflow_dispatch: {}
  schedule:
    # run every hour on the 5 between 9am and 5pm (4am and 12pm UTC), M-F
    - cron: "5 14-22 * * 1-5"
jobs:
  update-requirement:
    name: Update Multitool Versions
    runs-on: ubuntu-latest
    permissions:
      contents: read
    # disable running on anything but main
    if: ${{ github.ref == 'refs/heads/main' }}
    env:
      LOCKFILE: ./multitool.lock.json
    steps:
      - name: Get Token
        id: app-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ secrets.AUTOMATION_APP_ID }}
          private-key: ${{ secrets.AUTOMATION_PRIVATE_KEY }}
      - uses: actions/checkout@v4
        with:
          token: ${{ steps.app-token.outputs.token }}

      - name: Find Updates and Render Lockfile
        run: bazel run @multitool//tools/multitool:cwd -- --lockfile "$LOCKFILE" update

      - name: Commit Changes
        env:
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          BRANCH_NAME: "automation/update-multitool-lockfile"
        run: |
          if [[ -n "$(git diff "$LOCKFILE")" ]]
          then
            git config --local user.name 'Automation'
            git config --local user.email 'app-name[bot]@users.noreply.github.com'
            git checkout -b "${BRANCH_NAME}"
            git add "$LOCKFILE"
            git commit -m "Update Multitool Versions
            
            Updated with [update-multitool](${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}) by *${GITHUB_ACTOR}*
            "
            git push origin "${BRANCH_NAME}" -f
            gh pr create --fill --label "automerge" >> "$GITHUB_STEP_SUMMARY"
          fi
```

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

### Bazel Module Usage: Define Alternate Hub

Source: https://github.com/bazel-contrib/rules_multitool/blob/main/readme.md

Define an alternate multitool hub to group related tools. Lockfiles are combined according to the hub_name and follow specific merging rules.

```python
multitool.hub(hub_name = "alt_hub", lockfile = "//:other_tools.lock.json")
use_repo(multitool, "alt_hub")

# register the tools from this hub
register_toolchains("@alt_hub//toolchains:all")
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.