@dr-yaml/cli — dr-yaml command-line tool

Validate, simulate, document, and migrate CI/CD pipelines across GitHub Actions, CircleCI, and Bitrise — all locally, no server, no pipeline runner required.

Install

npm install -g @dr-yaml/cli
# one-off:
npx -y @dr-yaml/cli validate .github/workflows/ci.yml

The binary is dr-yaml. Internal @dr-yaml/* deps install automatically.

Commands

dr-yaml validate <file|dir|glob|url>

Parse and lint a pipeline. Walks .github/workflows/, .circleci/config.yml, and bitrise.yml automatically when pointed at a directory.

dr-yaml validate .github/workflows/ci.yml
dr-yaml validate .                     # recurse through conventional locations
dr-yaml validate 'workflows/*.yml'     # glob
dr-yaml validate https://github.com/owner/repo/blob/main/.github/workflows/ci.yml

Exit codes:

• 0 — clean (no errors, no warnings)
• 1 — parse error or lint error
• 2 — warnings only

--json emits a machine-readable { path, ok, issues, errorCount, warningCount } document.

dr-yaml simulate <file>

Run the deterministic simulator and print a per-job table.

dr-yaml simulate ci.yml --event pull_request --branch feat/foo \
  --secret AWS_KEY=true,GH_TOKEN=false

Flags: --event, --branch, --secret KEY=true,KEY2=false, --workflow <id>, --json. Every pipeline produces { path, platform, event, branch, jobs, warnings, totalDurationMin, totalCostUsd } under --json.

dr-yaml docs <file> [--format md|json] [--output <path>]

Markdown (default) or structured JSON description: triggers, jobs, inputs, secrets, Mermaid graph.

dr-yaml migrate <file> --to <gha|circleci|bitrise>

Cross-platform deterministic migration. Adds --with-llm to layer Claude- or GPT-assisted suggestions for features the target platform doesn't natively support.

dr-yaml migrate circleci/config.yml --to gha --output .github/workflows/migrated.yml
dr-yaml migrate bitrise.yml --to gha --with-llm --llm-provider anthropic --yes

LLM API keys come from ANTHROPIC_API_KEY / OPENAI_API_KEY in env, or --llm-api-key. Nothing is sent anywhere except directly to the provider you chose.

dr-yaml mcp

Launch the MCP server on stdio. Identical to running @dr-yaml/mcp directly — use this when you already have the CLI installed and want a single-binary surface.

Non-goals

• No secrets storage.
• No pipeline execution — simulation only.
• No write/edit of your YAML. migrate produces a new document; you review and commit it yourself.

Running from source (contributors)

bun install
bun run apps/cli/src/index.ts --help
# Or linked globally:
bun link --cwd apps/cli
dr-yaml --help

Related

• @dr-yaml/mcp — MCP server wrapping the same read-only surface for AI coding assistants.
• @dr-yaml/core — the shared orchestrator every CLI + MCP + web-app command calls into.

License

MIT.