{"id":30487550,"url":"https://github.com/technicalpickles/bktide","last_synced_at":"2026-04-07T23:03:57.431Z","repository":{"id":309974776,"uuid":"970696443","full_name":"technicalpickles/bktide","owner":"technicalpickles","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-09T12:24:06.000Z","size":1325,"stargazers_count":2,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-31T16:48:38.844Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/technicalpickles.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-22T11:58:42.000Z","updated_at":"2026-03-12T17:57:00.000Z","dependencies_parsed_at":"2025-08-14T23:25:37.321Z","dependency_job_id":"35e3c2f4-82c0-40b6-b45a-17c523ba7dfe","html_url":"https://github.com/technicalpickles/bktide","commit_stats":null,"previous_names":["technicalpickles/bktide"],"tags_count":65,"template":false,"template_full_name":null,"purl":"pkg:github/technicalpickles/bktide","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technicalpickles%2Fbktide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technicalpickles%2Fbktide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technicalpickles%2Fbktide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technicalpickles%2Fbktide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/technicalpickles","download_url":"https://codeload.github.com/technicalpickles/bktide/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technicalpickles%2Fbktide/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31530647,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"ssl_error","status_checked_at":"2026-04-07T16:28:06.951Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-24T17:30:15.072Z","updated_at":"2026-04-07T23:03:57.413Z","avatar_url":"https://github.com/technicalpickles.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bktide\n\nCommand-line interface for Buildkite CI/CD workflows with rich shell completions (Fish, Bash, Zsh) and Alfred workflow integration for macOS power users.\n\n## Features\n\n- **🚀 Workflow Management**: View and manage builds, pipelines, organizations, and annotations\n- **🔧 Smart Shell Completions**: Context-aware completions for Fish, Bash, and Zsh\n- **🎯 Alfred Integration**: macOS Alfred workflow for quick access to Buildkite data\n- **📊 Multiple Output Formats**: Plain text, JSON, or Alfred-compatible output\n- **🔐 Secure Token Storage**: System keychain integration for API credentials\n- **⚡ Performance**: Built-in caching for faster repeated operations\n- **🤖 AI/LLM Integration**: Export agent rules for Claude Code, Cursor, and other AI tools\n\n## Installation\n\n```bash\nnpm install -g bktide\n```\n\nOnce installed, use the `bktide` binary directly from your shell.\n\n## Shell Completions\n\nbktide supports auto-completion for Fish, Bash, and Zsh shells.\n\n### Quick Setup\n\n```bash\n# Fish\nbktide completions fish \u003e ~/.config/fish/completions/bktide.fish\n\n# Bash\necho 'source \u003c(bktide completions bash)' \u003e\u003e ~/.bashrc\n\n# Zsh  \necho 'source \u003c(bktide completions zsh)' \u003e\u003e ~/.zshrc\n```\n\nCompletions provide:\n- Command suggestions (ie `bktide \u003cTab\u003e`)\n- Option completions (ie `bktide builds --\u003cTab\u003e`)\n- Value completions (ie `bktide --format \u003cTab\u003e`)\n- Dynamic completions for organizations and pipelines (Fish with jq installed)\n\nSee [Shell Completions Guide](docs/shell-completions.md) for detailed installation and troubleshooting.\n\n## Documentation\n\nOur documentation is organized by audience to help you find what you need:\n\n### 📖 [User Documentation](docs/user/) - For end users\n- [Getting Started](docs/user/getting-started.md) - Quick start guide for new users\n- [Authentication](docs/user/authentication.md) - How to authenticate with Buildkite\n- [Shell Completions](docs/user/shell-completions.md) - Setting up auto-completion\n- [Troubleshooting](docs/user/troubleshooting.md) - Common issues and solutions\n- [Alfred Integration](docs/user/alfred/) - macOS Alfred workflow (installation, troubleshooting)\n\n### 👨‍💻 [Developer Documentation](docs/developer/) - For contributors\n- [Contributing Guide](docs/developer/contributing.md) - How to contribute to the project\n- [Development Guide](docs/developer/development.md) - Setup and coding guidelines\n- [Alfred Workflow Development](docs/developer/alfred-workflow-development.md) - Building and packaging\n- [Testing Strategy](docs/developer/testing/README.md) - Testing approach and procedures\n\n### 📚 [Reference Documentation](docs/reference/) - For everyone\n- [Changelogs](docs/reference/) - What changed and when\n- [Release Process](docs/reference/releasing.md) - How releases work\n\nSee [Documentation Overview](docs/README.md) for the complete structure and classification guide.\n\n## Testing\n\nRun the test suite with:\n```bash\nnpm test                       # Run all tests\nnpm run test:watch            # Watch mode for development  \nnpm run test:coverage         # Generate coverage report\nnpm run test:extract-patterns # Extract patterns from real data (requires token)\n```\n\nSee [Testing Strategy](docs/developer/testing/README.md) for details on the hybrid testing approach.\n\n## Usage\n\n### Show Your Login Information\n\n```bash\nbktide viewer\n```\n\n### List Your Organizations\n\n```bash\nbktide orgs\n```\n\n### List Pipelines in an Organization\n\n```bash\nbktide pipelines\n```\n\nAdditional options:\n```bash\n# Filter by organization\nbktide pipelines --org your-org-slug\n\n# Limit the number of results\nbktide pipelines --count 20\n\n# Filter pipelines by name\nbktide pipelines --filter payments\n```\n\n### List Your Builds\n\n```bash\nbktide builds\n```\n\nAdditional options:\n```bash\n# Filter by organization\nbktide builds --org your-org-slug\n\n# Filter by pipeline\nbktide builds --pipeline pipeline-slug\n\n# Filter by branch\nbktide builds --branch main\n\n# Filter by state\nbktide builds --state passed\n\n# Pagination\nbktide builds --count 20 --page 2\n\n# Output in JSON format\nbktide builds --format json\n\n# Output in Alfred-compatible JSON format\nbktide builds --format alfred\n```\n\n### Show Build Annotations\n\n```bash\nbktide annotations \u003cbuild\u003e\n```\n\nThe build reference can be specified in two formats:\n- **Slug format**: `org/pipeline/number` (e.g., `gusto/zenpayroll/1287418`)\n- **URL format**: `https://buildkite.com/org/pipeline/builds/number`\n\nAdditional options:\n```bash\n# Filter by context\nbktide annotations gusto/zenpayroll/1287418 --context rspec\n\n# Output in JSON format\nbktide annotations gusto/zenpayroll/1287418 --format json\n\n# Output in plain text format (default)\nbktide annotations https://buildkite.com/gusto/zenpayroll/builds/1287418 --format plain\n\n# Combine filtering and formatting\nbktide annotations gusto/zenpayroll/1287418 --context build-resources --format json\n```\n\n### Show Build Details\n\nView detailed information about a specific build including jobs and annotations.\n\n```bash\n# View build by slug format\nbktide build org/pipeline/123\n\n# View build by URL format\nbktide build https://buildkite.com/org/pipeline/builds/123\n```\n\nAdditional options:\n```bash\n# Fetch all jobs (handles pagination for large builds)\nbktide build org/pipeline/123 --jobs\n\n# Show failure details and error summaries\nbktide build org/pipeline/123 --failed\n\n# Include full annotation content\nbktide build org/pipeline/123 --annotations\n\n# Combine options for comprehensive view\nbktide build org/pipeline/123 --jobs --failed --annotations\n```\n\n### Show Pipeline Details\n\nView pipeline metadata and recent builds.\n\n```bash\n# View pipeline by slug format\nbktide pipeline org/pipeline\n\n# View pipeline by URL format\nbktide pipeline https://buildkite.com/org/pipeline\n\n# Show more recent builds\nbktide pipeline org/pipeline --count 50\n```\n\n### View Step Logs\n\nView logs for a specific build step.\n\n```bash\n# View logs by providing build reference and step ID\nbktide logs org/pipeline/123 \u003cstep-id\u003e\n\n# View logs from URL with step ID in query parameter\nbktide logs \"https://buildkite.com/org/pipeline/builds/123?sid=\u003cstep-id\u003e\"\n\n# Show all lines (default is last 50 lines)\nbktide logs org/pipeline/123 \u003cstep-id\u003e --full\n\n# Show last N lines\nbktide logs org/pipeline/123 \u003cstep-id\u003e --lines 100\n\n# Save logs to file\nbktide logs org/pipeline/123 \u003cstep-id\u003e --save logs.txt\n```\n\n**Note:** Viewing step logs requires `read_build_logs` scope on your API token.\n\n### Follow Logs in Real-Time\n\nStream logs as they're written (useful for watching running jobs):\n\n```bash\n# Follow logs until job completes\nbktide logs org/pipeline/123 \u003cstep-id\u003e --follow\n\n# Follow with custom poll interval (default: 3 seconds)\nbktide logs org/pipeline/123 \u003cstep-id\u003e --follow --poll-interval 5\n\n# Combine with other options\nbktide logs org/pipeline/123 \u003cstep-id\u003e --follow --lines 100\n```\n\n**Note:** Following logs uses polling (2 API calls per interval). For long-running jobs, consider using `--poll-interval 5` or higher to reduce API usage.\n\n### Smart Reference Command\n\nPaste any Buildkite URL or use short-hand formats, and bktide will figure out what to show.\n\n**Supported formats:**\n\n```bash\n# Pipeline view (shows metadata + recent builds)\nbktide gusto/schemaflow\nbktide https://buildkite.com/gusto/schemaflow\n\n# Build view (shows comprehensive build details)\nbktide gusto/schemaflow/76\nbktide gusto/schemaflow#76\nbktide https://buildkite.com/gusto/schemaflow/builds/76\n\n# Step logs (shows build context + step logs)\nbktide https://buildkite.com/gusto/schemaflow/builds/76?sid=019adb19-bd83-4149-b2a7-ece1d7a41c9d\n```\n\n**Log display options:**\n\n```bash\n# Show last 50 lines (default)\nbktide https://buildkite.com/org/pipeline/builds/123?sid=\u003cstep-id\u003e\n\n# Show all lines\nbktide https://buildkite.com/org/pipeline/builds/123?sid=\u003cstep-id\u003e --full\n\n# Show last N lines\nbktide https://buildkite.com/org/pipeline/builds/123?sid=\u003cstep-id\u003e --lines 100\n\n# Save logs to file\nbktide https://buildkite.com/org/pipeline/builds/123?sid=\u003cstep-id\u003e --save logs.txt\n```\n\n**Note:** Viewing step logs requires `read_build_logs` scope on your API token.\n\n### Generate Shell Completions\n\n```bash\n# Generate completions for your shell\nbktide completions fish\nbktide completions bash\nbktide completions zsh\n\n# Auto-detect your shell and generate completions\nbktide completions\n```\n\n### AI/LLM Integration\n\nExport agent rules to teach AI assistants how to use bktide for CI debugging.\n\n```bash\n# View the rules\nbktide prime\n\n# Append to Claude Code memory\nbktide prime \u003e\u003e ~/.claude/CLAUDE.md\n\n# Append to Cursor rules\nbktide prime \u003e\u003e .cursor/rules.md\n```\n\nThe rules include common workflows for investigating failing builds and integrating with GitHub PRs.\n\n## API Token\n\nYou'll need a Buildkite API token. Create one at:\nhttps://buildkite.com/user/api-access-tokens\n\n### Required Scopes\n\nEnable these scopes when creating your token:\n\n- **GraphQL API Access** - Required for all API queries\n- **Read Builds** - View builds, jobs, and logs\n- **Read Organizations** - List and access organizations\n- **Read Pipelines** - View pipeline configurations\n- **Read User** - Access your user information\n\nAll five scopes are required for full bktide functionality.\n\n### Providing your token\n\nYou can provide your token in one of these ways:\n\n- `-t, --token \u003ctoken\u003e`: e.g. `bktide orgs --token abc123`\n- `BK_TOKEN` environment variable: e.g. `BK_TOKEN=abc123 bktide orgs`\n- Store once and reuse: `bktide token --store`\n\nManage stored token:\n\n```bash\nbktide token --check   # See if a token is stored\nbktide token --reset   # Remove stored token\n```\n\n## Visual Features\n\nThe CLI provides a modern visual experience with color-coded information and clear hierarchy:\n\n### Color-Coded Build Status\nBuild statuses are displayed with intuitive colors for quick scanning:\n- **Blue** (✓) - Passed builds\n- **Orange** (✖) - Failed builds  \n- **Cyan** (↻) - Running builds\n- **Yellow** (⚠) - Blocked/warning states\n- **Gray** (−) - Skipped/inactive states\n\n### Visual Hierarchy\n- **Bold + underlined headers** for table columns\n- **Cyan highlighting** for identifiers (#1234, IDs)\n- **Magenta** for numeric counts\n- **Dimmed text** for auxiliary information and tips\n- **Arrow indicators** (→) for actionable tips\n\n### Accessibility\n- **Colorblind-safe palette** - Uses blue/orange instead of green/red\n- **NO_COLOR support** - Set `NO_COLOR=1` for no colors\n- **ASCII mode** - Use `BKTIDE_ASCII=1` for screen reader compatibility\n- **Symbols with text fallbacks** - Information never relies solely on color\n\n### Smart Empty States\nWhen no results are found, helpful suggestions guide you:\n```\nNo builds found\n\nTry specifying an organization with --org \u003cname\u003e\nUse --count to increase the number of results\n```\n\n### Enhanced Error Messages\nErrors provide clear context and actionable solutions:\n```\n✖ Error: Authentication Failed\n\nThe provided token is invalid or expired.\n\nTo fix this:\n  1. Get a new token from Buildkite\n  2. Run: bktide token --store\n  3. Try your command again\n```\n\n## Snapshot: Offline Build Analysis\n\nWhen you need to do deep debugging or feed build data into other tools, use `snapshot` to download complete build data locally.\n\n### Capture a Build Snapshot\n\n```bash\n# Capture failed steps from a build\nbktide snapshot https://buildkite.com/org/pipeline/builds/123\nbktide snapshot org/pipeline/123\n\n# Capture all steps (not just failures)\nbktide snapshot org/pipeline/123 --all\n\n# Force re-fetch (bypass incremental update)\nbktide snapshot org/pipeline/123 --force\n\n# Custom output location\nbktide snapshot org/pipeline/123 --output-dir ./investigation\n```\n\nSubsequent runs detect changes automatically. If the build hasn't changed, it shows \"Snapshot already up to date\" and skips re-fetching.\n\n### What Gets Captured\n\nSnapshots are saved to `./tmp/bktide/snapshots/org/pipeline/build/` (relative to cwd) with:\n\n- **manifest.json** - Build metadata and step index for quick filtering\n- **build.json** - Complete build data from Buildkite API\n- **annotations.json** - Test failures, warnings, and structured information from annotations\n- **steps/NN-name/log.txt** - Full logs for each step\n- **steps/NN-name/step.json** - Step metadata (state, exit code, timing)\n\n### Common Use Cases\n\n**Find what failed:**\n\n```bash\ncd ./tmp/bktide/snapshots/org/pipeline/123\njq -r '.steps[] | select(.state == \"failed\") | \"\\(.id): \\(.label)\"' manifest.json\n```\n\n**View test failure summaries:**\n```bash\njq -r '.annotations[] | select(.style == \"error\") | \"\\(.context): \\(.body_html)\"' annotations.json\n```\n\n**Search logs for errors:**\n```bash\ngrep -r \"Error\\|Exception\" steps/\n```\n\n**Feed to AI agents:**\n```bash\nbktide snapshot org/pipeline/123\nclaude \"analyze failures in ./tmp/bktide/snapshots/org/pipeline/123\"\n```\n\n**Share with teammates:**\n```bash\ntar -czf build-123-investigation.tar.gz ./tmp/bktide/snapshots/org/pipeline/123\n```\n\n**Note:** Add `./tmp/` to your `.gitignore` if using the default location.\n\n## Global Options\n\nThese flags work with all commands:\n\n- `--log-level \u003clevel\u003e`: trace|debug|info|warn|error|fatal (default: info)\n- `-d, --debug`: verbose debug output and detailed errors\n- `--no-cache`: disable API response caching\n- `--cache-ttl \u003cms\u003e`: set cache TTL in milliseconds\n- `--clear-cache`: clear cached data before running\n- `-t, --token \u003ctoken\u003e`: provide Buildkite API token (or use `BK_TOKEN`)\n- `--save-token`: save token to system keychain\n- `-f, --format \u003cformat\u003e`: plain|json|alfred (affects output and errors)\n- `--color \u003cmode\u003e`: auto|always|never (controls color in plain format)\n- `-q, --quiet`: suppress non-error output (success messages, tips)\n- `--tips`: show helpful tips after operations (default: true)\n- `--no-tips`: hide helpful tips\n\n### Output Behavior\n\n- Plain format (default): human-friendly output with color-coded statuses, bold headers, and visual hierarchy. Progress indicators (spinners for indeterminate operations, progress bars for operations with known totals) show during long operations only in interactive TTYs and are cleared on completion (no residual lines). Tips appear dimmed with arrow indicators (→) at the end of output.\n- JSON/Alfred formats: strictly machine-readable; no extra lines, no colors, no spinners or confirmations.\n- Streams: results go to stdout; errors go through the error formatter. When using `--format json|alfred`, only the formatted payload is printed.\n- Colors: by default `--color auto` enables color in TTYs with semantic coloring (blue for success, orange for errors, etc.). Use `--color never` or `NO_COLOR=1` to disable. Use `--color always` to force color in plain output.\n- Accessibility: Full functionality without colors - symbols provide visual cues (✓, ✖, ⚠, →) with ASCII fallbacks when `BKTIDE_ASCII=1` is set.\n\n# Logging System\n\nThe CLI uses a structured logging system based on Pino. This provides several benefits:\n\n- Different log levels (trace, debug, info, warn, error, fatal)\n- JSON logs saved to disk (in `log/cli.log`)\n- Pretty-printed logs to the console\n- Performance measurements\n\n## Log Level Configuration\n\nYou can configure the log level with the `--log-level` option:\n\n```bash\nbktide orgs --log-level=debug  # Show debug messages\nbktide builds --log-level=trace # Show all messages including trace\n```\n\nAvailable log levels (from most to least verbose):\n- trace: Very detailed tracing for debugging\n- debug: Detailed information for developers\n- info: General information (default)\n- warn: Warning conditions\n- error: Error conditions\n- fatal: Severe errors causing termination\n\n## Log Files\n\nAll logs are written to `~/.local/state/bktide/logs/cli.log` in JSON format, which can be processed with tools like jq:\n\n```bash\n# View recent errors\ncat ~/.local/state/bktide/logs/cli.log | grep -v '\"level\":30' | jq\n\n# Analyze performance \ncat ~/.local/state/bktide/logs/cli.log | jq 'select(.duration != null) | {msg, duration}'\n``` ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechnicalpickles%2Fbktide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftechnicalpickles%2Fbktide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechnicalpickles%2Fbktide/lists"}