gh-technicalpickles-pickled-claude-plugins-plugins-ci-cd-tools/skills/buildkite-status/references/tool-capabilities.md

Tool Capabilities Reference

This document provides complete capability information for all Buildkite status checking tools.

Overview

Three tool categories exist with different strengths and limitations:

1. MCP Tools - Direct Buildkite API access via Model Context Protocol
2. bktide CLI - Human-readable command-line tool (npm package)
3. Bundled Scripts - Helper wrappers in this skill's scripts/ directory

Capability Matrix

Capability	MCP Tools	bktide	Scripts	Notes
List organizations	✅ buildkite:list_orgs	❌	❌
List pipelines	✅ buildkite:list_pipelines	✅ bktide pipelines	❌
List builds	✅ buildkite:list_builds	✅ bktide builds	✅ find-commit-builds.js	Scripts are specialized
Get build details	✅ buildkite:get_build	✅ bktide build	❌
Get annotations	✅ buildkite:list_annotations	✅ bktide annotations	❌
Retrieve job logs	✅ buildkite:get_logs	❌ NO	✅ get-build-logs.js	bktide cannot get logs
Get log metadata	✅ buildkite:get_logs_info	❌	❌
List artifacts	✅ buildkite:list_artifacts	❌	❌
Wait for build	✅ buildkite:wait_for_build	❌	✅ wait-for-build.js	MCP preferred
Unblock jobs	✅ buildkite:unblock_job	❌	❌
Real-time updates	✅	❌	✅	Via polling
Human-readable output	❌ (JSON)	✅	Varies
Works offline	❌	❌	❌	All need network
Requires auth	✅ (MCP config)	✅ (BK_TOKEN)	✅ (uses bktide)

Detailed Tool Information

MCP Tools (Primary)

Access Method: mcp__MCPProxy__call_tool("buildkite:<tool>", {...})

Authentication: Configured in MCP server settings (typically uses BUILDKITE_API_TOKEN)

Pros:

• Complete API coverage
• Always available (no external dependencies)
• Real-time data
• Structured JSON responses

Cons:

• Verbose JSON output
• Requires parsing for human reading

Key Tools:

buildkite:get_build

Get detailed build information including job states, timing, and metadata.

Parameters:

• org_slug (required): Organization slug
• pipeline_slug (required): Pipeline slug
• build_number (required): Build number
• detail_level (optional): "summary" | "detailed" | "complete"
• job_state (optional): Filter jobs by state ("failed", "passed", etc.)

Returns: Build object with jobs array, state, timing, author, etc.

buildkite:get_logs

THE CRITICAL TOOL - Retrieve actual log output from a job.

Parameters:

• org_slug (required): Organization slug
• pipeline_slug (required): Pipeline slug
• build_number (required): Build number
• job_id (required): Job UUID (NOT step ID from URL)

Returns: Log text content

Common Issues:

• "job not found" → Using step ID instead of job UUID
• Empty response → Job hasn't started or finished yet

buildkite:wait_for_build

Poll build until completion.

Parameters:

• org_slug (required): Organization slug
• pipeline_slug (required): Pipeline slug
• build_number (required): Build number
• timeout (optional): Seconds until timeout (default: 1800)
• poll_interval (optional): Seconds between checks (default: 30)

Returns: Final build state when complete or timeout

bktide CLI (Secondary)

Access Method: npx bktide <command>

Authentication: BK_TOKEN environment variable or ~/.bktide/config

Pros:

• Human-readable colored output
• Intuitive command structure
• Good for interactive terminal work

Cons:

• External npm dependency
• CANNOT retrieve job logs (most critical limitation)
• Limited compared to full API
• Requires npx/node installed

Key Commands:

npx bktide pipelines <org>                    # List pipelines
npx bktide builds <org>/<pipeline>            # List recent builds
npx bktide build <org>/<pipeline>/<number>    # Build details
npx bktide build <org>/<pipeline>/<number> --jobs  # Show job summary
npx bktide build <org>/<pipeline>/<number> --failed # Show failed jobs only
npx bktide annotations <org>/<pipeline>/<number>    # Show annotations

Critical: bktide has NO command for retrieving logs. The build command shows job states and names, but NOT log content.

Bundled Scripts (Tertiary)

Access Method: ~/.claude/skills/buildkite-status/scripts/<script>.js

Authentication: Use bktide internally (requires BK_TOKEN)

Pros:

• Purpose-built for specific workflows
• Handle common use cases automatically
• Provide structured output

Cons:

• Depend on bktide (external dependency)
• Limited to specific use cases
• May have version compatibility issues

Available Scripts:

find-commit-builds.js

Find builds matching a specific commit SHA.

Usage:

~/.claude/skills/buildkite-status/scripts/find-commit-builds.js <org> <commit-sha>

Returns: JSON array of matching builds

wait-for-build.js

Monitor build until completion (background-friendly).

Usage:

~/.claude/skills/buildkite-status/scripts/wait-for-build.js <org> <pipeline> <build> [options]

Options:

• --timeout <seconds>: Max wait time (default: 1800)
• --interval <seconds>: Poll interval (default: 30)

Exit codes:

• 0: Build passed
• 1: Build failed
• 2: Build canceled
• 3: Timeout

get-build-logs.js (NEW - to be implemented)

Retrieve logs for a failed job with automatic UUID resolution.

Usage:

~/.claude/skills/buildkite-status/scripts/get-build-logs.js <org> <pipeline> <build> <job-label-or-uuid>

Features:

• Accepts job label or UUID
• Automatically resolves label → UUID
• Handles step ID confusion
• Formats output for readability

Decision Matrix: Which Tool to Use

Use MCP Tools When:

• Getting build details
• Retrieving job logs (ONLY option with bktide)
• Waiting for builds (preferred over script)
• Unblocking jobs
• Automating workflows
• Need structured data

Use bktide When:

• Interactive terminal work
• Want human-readable summary
• Listing pipelines/builds
• Getting quick status overview
• NOT when you need logs (it can't do this)

Use Scripts When:

• Need specialized workflow (find commits)
• Want background monitoring
• MCP tools fail (fallback)
• Automating repetitive tasks

Common Mistakes

❌ Trying to get logs with bktide

Don't: npx bktide build <org>/<pipeline>/<number> --logs

Why: This flag doesn't exist. bktide cannot retrieve logs.

Do: Use buildkite:get_logs MCP tool

❌ Using step ID for log retrieval

Don't: Extract sid=019a5f... from URL and use directly

Why: Step IDs ≠ Job UUIDs. MCP tools need job UUIDs.

Do: Call buildkite:get_build to get job details, extract uuid field

❌ Abandoning MCP tools when script fails

Don't: "Script failed, I'll use GitHub instead"

Why: Scripts depend on bktide. MCP tools are independent.

Do: Use MCP tools directly when scripts fail

Troubleshooting

Issue: "job not found" when calling get_logs

Diagnosis: Using step ID instead of job UUID

Solution:

1. Call buildkite:get_build with detail_level: "detailed"
2. Find job by label field
3. Extract uuid field
4. Use that UUID in get_logs call

Issue: bktide command not found

Diagnosis: npm/npx not installed or not in PATH

Solution:

1. Use MCP tools instead (preferred)
2. Or install: npm install -g @anthropic/bktide

Issue: Empty logs returned

Diagnosis: Job hasn't completed or logs not available yet

Solution:

1. Check job state - should be terminal (passed/failed/canceled)
2. Wait for job to finish
3. Check job started_at and finished_at timestamps

See Also

• SKILL.md - Main skill documentation
• troubleshooting.md - Common errors and solutions
• url-parsing.md - Understanding Buildkite URLs