Mutagent cli
MutagenT CLI - the command-line client for the MutagenT platform. Guides coding agents through setup (login, init, providers, workspaces), installing MutagenT packages (helix, diagnostics, evaluator), and sending product feedback. Triggers: "mutagent", "mutagent cli", "mutagent login", "set up mutagent", "install diagnostics", "install evaluator", "install helix", "mutagent install", "send feedback", "mutagent feedback", "report a bug", "usage", "quota", "install skill", "install hooks".From its SKILL.md
npx -y skills add mutagent-io/skills --skill mutagent-cliAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its file declares
Copied from the file, not written here
The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
11.9 KB, as published. Nobody here has run it
MutagenT CLI Skill
Installed to dev environments via
mutagent skills install. Bundled with the CLI binary so it stays version-aligned. This published copy is the canonical reference — edit upstream and re-publish, never the installed copy.
CLI Prerequisite Check (RUN FIRST)
Before executing ANY workflow step, verify the CLI is installed and version-compatible:
Step 1 -- Check CLI presence:
mutagent --version --json
Step 2 -- If command not found (error / not on PATH):
This is the Path 2 onboarding case: the Skill was installed first (e.g. from a skill registry, manually, or bundled in someone else's CLAUDE.md), but the CLI itself isn't installed yet. Do NOT just dump install instructions and stop -- proactively offer to install it.
2a. Detect the user's package manager (best-effort — check in this order):
# In the user's project root (cwd):
test -f bun.lockb && echo "bun"
test -f pnpm-lock.yaml && echo "pnpm"
test -f yarn.lock && echo "yarn"
test -f package-lock.json && echo "npm"
# Fallback: which bun || which pnpm || which yarn || which npm
If multiple lockfiles exist, prefer in order: bun > pnpm > yarn > npm.
If no lockfile and the user is in a non-JS project (e.g. Python, Go), ask which they prefer.
2b. Ask the user via AskUserQuestion (do NOT auto-install without consent):
"The MutagenT CLI is not installed yet. I can install it globally via
<detected-pm>. Proceed?"
Options to present:
- Yes, install globally with
<detected-pm>(Recommended) -- runs<pm> add -g @mutagent/cli(ornpm install -g @mutagent/clifor npm) - Yes, but use a different package manager -- prompt for choice (npm / bun / pnpm / yarn)
- No, I'll install it myself -- show the four install commands as a verbatim block; STOP and wait for the user to install
- Skip — I have it installed via a different path -- ask the user to add it to PATH and re-invoke
2c. On user approval (option 1 or 2), run the install command in a Bash tool call:
# bun
bun add -g @mutagent/cli
# npm
npm install -g @mutagent/cli
# pnpm
pnpm add -g @mutagent/cli
# yarn
yarn global add @mutagent/cli
Show the install output to the user verbatim. After it completes, re-run Step 1 (mutagent --version --json) to confirm the CLI is now on PATH. If the post-install version check still fails (e.g. global bin not on PATH), tell the user:
"Install succeeded but
mutagentisn't on PATH yet. Common fixes:
- bun:
export PATH=\"$HOME/.bun/bin:$PATH\"- npm: check
npm config get prefixand add<prefix>/binto PATH- pnpm:
pnpm setupthen restart your shell- yarn:
yarn global binand add that path to PATH" Then ask the user to restart their shell or source the relevant rc file, and re-invoke me.
2d. On rejection (option 3 or 4), output the four install commands as a verbatim block and STOP. Do NOT proceed with any workflow until the user confirms the CLI is installed and re-invokes the skill.
# Pick one (Recommended in order: bun > pnpm > yarn > npm)
bun add -g @mutagent/cli
pnpm add -g @mutagent/cli
yarn global add @mutagent/cli
npm install -g @mutagent/cli
Why proactive install (not just "stop and tell"): a user invoking this Skill has already shown intent to use MutagenT. Forcing them to context-switch to a separate terminal, copy-paste an install command, and re-invoke the agent is friction that often loses the user. Asking once + installing on consent is the smoother path. The opt-out (option 3/4) preserves user control.
Step 3 -- Version compatibility check:
Parse _compat.cliVersion from the --version --json output and compare against
metadata.skill_min_cli_version (above in this file's frontmatter, currently 0.1.163).
-
If
cliVersion >= metadata.skill_min_cli_version: all good, proceed normally. -
If
cliVersion < metadata.skill_min_cli_version: emit a PROMINENT PERSISTENT WARN to the user:Warning: CLI version mismatch: Your
mutagentCLI is{cliVersion}but this Skill requires>= 0.1.163. Some features may not work correctly. Upgrade:npm install -g @mutagent/cli@latestDO NOT BLOCK -- proceed with the requested workflow after showing the warn. Re-emit this warn at the start of every subsequent Skill invocation until the user upgrades.
Per decision D4 (locked 2026-05-03): version mismatch is warn-only, never a hard block.
Login (RUN SECOND — most commands are login-gated)
Install, feedback, usage, workspaces, and providers commands all require an authenticated session. Establish it early:
- CI / automated:
export MUTAGENT_API_KEY=mt_... && mutagent login --json-- no browser, no prompts. - Onboarding a user:
mutagent login --browser --json-- CLI prints auth URL to stdout, polls 5 min. Surface the URL verbatim to the user.--non-interactiveis NOT needed when--browseris set.
mutagent login is canonical. mutagent auth login is a back-compat alias. Both delegate to a single shared implementation; they are thin wrappers and stay that way by design.
Check current state anytime with mutagent auth status --json.
Command Surface (active commands)
Run mutagent <command> --help for the authoritative, current flag list — this
skill never inlines flags. The active surface:
| Command | Purpose | Workflow |
|---|---|---|
login / auth | Authenticate; check/clear session | references/workflows/setup.md |
init | Interactive project setup wizard | references/workflows/setup.md |
config | View/set local CLI config | references/workflows/setup.md |
workspaces | List/select active workspace | references/workflows/setup.md |
providers | List providers + model catalog | references/workflows/setup.md |
usage | Show usage + quota | references/workflows/setup.md |
skills install | Install this skill into a project | references/workflows/setup.md |
hooks install | Install Claude Code telemetry hooks | references/workflows/setup.md |
install <pkg> | Install helix / diagnostics / evaluator | references/workflows/install.md |
feedback send | Send product feedback | references/workflows/feedback.md |
Core Rules -- NON-NEGOTIABLE
--jsonon EVERY command. No exceptions. Agents use JSON mode exclusively.<command> --helpBEFORE first use of any command. The CLI is the source of truth for flags -- this skill never inlines them.- Login before login-gated commands. install, feedback, usage, workspaces, and providers require an authenticated session. Run
mutagent login(or setMUTAGENT_API_KEY) first. - Show command output to the user. Command output appears in bash blocks the user may not see -- always present the key results in your chat reply.
- Confirm before writing to the user's machine or spending.
install,skills install, andhooks installwrite files or install packages -- state what will happen and get confirmation first.
Task Router -- route by user intent
Match the user's first request. Load ONLY the matching subfile per the table. Do NOT preload the whole set.
| User said / signal detected | Load subfile | Why |
|---|---|---|
| "log in", "authenticate", "set up mutagent", "init", "which workspace", "what models", "usage", "quota", "install the skill", "install hooks" | references/workflows/setup.md | Auth + project setup + discovery commands |
| "install helix", "install diagnostics", "install evaluator", "add mutagent package" | references/workflows/install.md | Login-gated meta-installer |
| "send feedback", "report a bug", "file feedback", "the CLI crashed" | references/workflows/feedback.md | Product feedback (+ optional transcript) |
| Unclear / first time | run mutagent --help --json then reroute | Discover the surface before acting |
Subfile Map
| File | WHEN to load | WHY |
|---|---|---|
| references/workflows/setup.md | User is onboarding: login, init, config, workspaces, providers, usage, skill/hooks install | Auth + configuration + discovery |
| references/workflows/install.md | User wants to install a MutagenT package | install <helix|diagnostics|evaluator> meta-command |
| references/workflows/feedback.md | User wants to send feedback or report a bug | feedback send + --attach-transcript |
MANDATORY: Verbatim Card Display Protocol
If a mutagent CLI response contains _directive.renderedCard, your FIRST action
MUST be to copy that text byte-for-byte into your chat reply BEFORE running any
further command, asking any question, or doing any other work.
The card also appears on stderr (auto-echoed by the CLI via echoDirectiveToStderr)
but you MUST STILL render it in chat -- bash/stderr blocks may be collapsed in the
user's UI and they cannot read them.
- Do NOT summarize, paraphrase, or truncate any line of the card.
- Do NOT skip the card to "save tokens."
- Do NOT delay rendering until "after the next step."
- This applies whether
_directive.displayis'status_card'or absent -- the trigger is the presence ofrenderedCard, not the display tag. - Failure to display the card verbatim = protocol violation.
Anti-patterns -- NEVER do these
- Run any command without
--json - Inline CLI flags from memory -- always read
--helpfirst - Skip showing command output results to the user
- Run a login-gated command before establishing a session
- Install a package or write skill/hooks files without user confirmation
Error Recovery -- Agent-Aware Bug Reporting
When ANY mutagent CLI command returns a non-zero exit code or an error response:
- Show the error to the user (always) -- reproduce the exact command and output.
- ASK the user if they want to file a bug report with session context.
- On user approval, send feedback with the session transcript attached:
mutagent feedback send "<one-line summary of the failure>" \ --category cli --attach-transcript --json--attach-transcript(bare) auto-detects the newest coding-agent session JSONL and uploads it as context.- Use
--category stage:<spec|build|evaluate|diagnose|optimize>when the failure is about a specific lifecycle stage rather than the CLI itself.
See references/workflows/feedback.md for the full feedback surface.
If mutagent feedback send itself fails
If the feedback command returns a non-zero exit code, DO NOT retry silently. Show the user:
- The output of
mutagent auth status(confirms login state). - The fallback: open https://app.mutagent.io and use the in-app feedback form.
Extensibility
Add workflows/custom-<name>.md with a markdown heading (or frontmatter
triggers: ["phrase"]) -- auto-discovered by the sync pipeline. No rebuild of the
CLI source needed; just re-run bun run sync-skill.
What ships with it: 11 files
96.2 KB alongside SKILL.md
references/
- concepts/dataset-design.md8.4 KB
- concepts/eval-criteria.md20.3 KB
- concepts/prompt-variables.md7.3 KB
- concepts/scorecard-output.md11.1 KB
- workflows/agents.md6.3 KB
- workflows/dataset-curation.md7.4 KB
- workflows/eval-creation.md9.2 KB
- workflows/exploration.md7.0 KB
- workflows/optimization.md12.0 KB
- workflows/tracing.md5.6 KB
- CHANGELOG.md1.6 KB