Maestro CLI Skill | Agent Skills

Maestro CLI

Query Maestro/BAR data via the mstro CLI tool instead of loading MCP tools into context. Same data, same caching, zero context tax — agents discover capabilities progressively through --help and mstro guide.

When to Use This Skill

Use this skill when:

You need Maestro/BAR data but the maestro MCP server isn't configured
You're scripting or chaining commands with jq, grep, or other CLI tools
You want structured JSON output for downstream processing
The task is one-shot (not a multi-turn conversational investigation)

Prefer MCP-based skills (flow-analysis, flow-tracing) when:

The maestro MCP server is already loaded in your tool list
You're doing multi-turn conversational investigation
You need markdown-formatted output with visual indicators

Installation

dotnet tool install -g lewing.maestro.mcp

After installation, mstro is available globally. Verify: mstro --help

Note: The same package (lewing.maestro.mcp) serves as both a .NET global tool (providing the mstro CLI) and an MCP server (via dotnet dnx). The CLI is what this skill uses.

Authentication

Three-tier cascade (automatic fallback):

MAESTRO_BAR_TOKEN env var — explicit PAT
Cached Entra ID — reuses darc authenticate credentials from ~/.darc/.auth-record-*
Anonymous — read-only fallback (may be rate-limited)

Run darc authenticate once for persistent credentials.

Progressive Discovery

Don't memorize commands. Discover them:

mstro --help              # All commands, one line each
mstro <command> --help    # Parameters for a specific command
mstro <command> --schema  # JSON response field names (for jq pipelines)
mstro guide               # Workflow-organized guide (~3KB)

Before writing jq queries, run --schema to see the response shape:

mstro subscription-health --schema   # → shows StaleSubs[].Id, .BuildsBehind, etc.
mstro latest-build --schema          # → shows Id, Repository, Commit, etc.

Common Patterns

All query commands support --json (structured output) and --no-cache (fresh data).

Check subscription health

mstro subscription-health --target-repository https://github.com/dotnet/dotnet --json

Find latest build

mstro latest-build https://github.com/dotnet/runtime --channel-name ".NET 10.0.1xx SDK" --json

Check codeflow status

mstro codeflow-statuses --json

Trace a build graph

mstro build-graph <build-id> --json

Trigger a stale subscription

# Provide --source-repository + --channel-name (auto-resolves latest build)
mstro trigger-subscription <guid> --source-repository https://github.com/dotnet/runtime --channel-name ".NET 10.0.1xx SDK"
# Or provide --build-id directly. Add --force to overwrite stale PR branch.

Chaining with jq

Use mstro <command> --schema to see all response fields before writing jq queries.

# Count stale subscriptions (StaleSubs[].Id, .BuildsBehind, .SourceRepository, .ChannelName)
mstro subscription-health --target-repository https://github.com/dotnet/dotnet --json | jq '.StaleSubs | length'

# Filter channels by name
mstro channels --json | jq '.[] | select(.Name | contains("10.0"))'

# Get build ID then trace graph
BUILD_ID=$(mstro latest-build https://github.com/dotnet/runtime --json | jq -r '.Id')
mstro build-graph $BUILD_ID --json

Cache

Shared SQLite cache at ~/.mstro/cache.db (WAL mode). Cache is shared between CLI and MCP server instances — using the CLI warms the cache for MCP and vice versa.

mstro cache status — show cache stats
mstro cache clear — clear all cached data
--no-cache on any command bypasses cache

Agent Skills: Maestro CLI

Install this agent skill to your local

Skill Files