beaker-usage

Launch, monitor, pull, and cancel hosted Beaker optimization runs via the beaker CLI.

5|Updated Aug 5, 2026
One-click install
npx skills add https://github.com/rilixai/beaker-skill --skill beaker-usage-rilixai
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: beaker-usage
Source: https://github.com/rilixai/beaker-skill/tree/main/skills/beaker-usage
Command: npx skills add https://github.com/rilixai/beaker-skill --skill beaker-usage-rilixai

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Operating hosted Beaker optimization runs requires many CLI steps—selecting the right agent and integration, resolving remote branches and datasets, authorizing launches, polling status, pulling results, and cancelling runs—each with strict preconditions and exit-code semantics that are easy to get wrong. ## Core Features & Use Cases - Run Lifecycle Management: Launch agent optimization runs with beaker run trigger, monitor with bounded polling, pull completed results, and cancel runs safely with explicit authorization. - Launch Discovery: Verify auth and GitHub connection, select the correct agent by matching github_repository, list remote branches and hosted datasets, and check required environment variables before launching. - Model Comparison: Optionally launch comparison runs with 1–8 --optimization-model values drawn from beaker model list --available-only, only when the developer explicitly requests it. - Use Case: A developer asks to "launch a Beaker optimization run on the staging branch with dataset prompts@v3." The skill validates the connection, confirms the branch and dataset, states the exact launch parameters, and triggers the run—then reports the full run ID and UI URL. ## Quick Start Ask your agent to launch a Beaker optimization run for this repository and it will discover the connected agent, dataset, and branch before triggering the hosted run.

Frequently Asked Questions about beaker-usage

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I launch a Beaker optimization run from the CLI?

Run `beaker run trigger --integration-id <id> --agent <agent> --dataset <name@revision> --json` after verifying auth, GitHub connection, and required environment variables. Launch only after explicit developer authorization, and capture the full run ID and web URL from the JSON output.

How do I monitor a Beaker run until it completes?

Use `beaker run status <run-id> --watch --poll-interval 15 --poll-timeout 45 --json` for bounded polling. Exit code 3 means the run is still active, 0 means completed, and 1 means terminal but unsuccessful—report meaningful state changes without implying setup is unfinished.

Can I pass a git tag or commit SHA to beaker run trigger?

No. Hosted GitHub sources accept remote branches only; tags and commit SHAs passed via `--ref` return a 422 error. Ask for a remote branch pointing to the desired commit, preferably one returned by `beaker github branches`.

When should I use beaker-usage versus beaker-setup?

Use beaker-usage to operate an already-configured integration: launching, monitoring, pulling results, and cancelling runs. If the config, agent, GitHub association, dataset contract, or integration is missing or broken, stop and use beaker-setup instead of repairing it incidentally.

How do I compare multiple models in a Beaker run?

Repeat `--optimization-model provider:model` 1–8 times on `beaker run trigger`, using only models from `beaker model list --available-only --json`. Do this only when the developer explicitly requests a comparison; the default run optimizes the production system.

Why does beaker run status return exit code 3?

Exit code 3 means the run is still active or a bounded poll timed out—it is not a failure. Continue monitoring only if the developer requested it; exit 0 means completed, 1 means terminal but unsuccessful, and 2 means a client or lookup error.