From 756506e4726dc620b15ee8f4194f68fee8b95d94 Mon Sep 17 00:00:00 2001
From: Ajax Davis <thomasalwyndavis@gmail.com>
Date: Wed, 26 Nov 2025 22:51:43 +1000
Subject: [PATCH] docs: add CLI debugging section to CLAUDE.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document using GitHub CLI (gh) and Vercel CLI for debugging:
- GitHub Actions workflow runs and job logs
- Vercel deployments and runtime logs
- Common debugging workflows for each tool

Helps developers debug CI/CD issues efficiently from the terminal.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CLAUDE.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index b7e760d..c15117c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -240,3 +240,68 @@ pnpm format
 - **Documentation:** Storybook
 - **CI/CD:** GitHub Actions + Changesets
 - **Git Hooks:** Lefthook
+
+### Debugging CI/CD with CLI Tools
+
+When debugging CI failures or deployment issues, use command-line tools for efficient investigation:
+
+#### GitHub CLI (`gh`)
+
+Debug GitHub Actions CI runs:
+
+```bash
+# List recent workflow runs
+gh run list --limit 10
+
+# View specific run details
+gh run view <run-id>
+
+# View failed job logs
+gh run view <run-id> --log-failed
+
+# View specific job logs
+gh run view <run-id> --job <job-id> --log
+
+# Rerun failed jobs
+gh run rerun <run-id> --failed
+```
+
+**Common debugging workflow:**
+1. `gh run list` - Find the failed run ID
+2. `gh run view <run-id> --log-failed` - See what failed
+3. Fix the issue locally
+4. Push and monitor: `gh run watch`
+
+#### Vercel CLI
+
+Debug deployments and preview environments:
+
+```bash
+# List deployments
+vercel ls
+
+# View deployment details
+vercel inspect <deployment-url>
+
+# View deployment logs
+vercel logs <deployment-url>
+
+# Pull environment variables
+vercel env pull
+
+# Link local project to Vercel project
+vercel link
+```
+
+**Common debugging workflow:**
+1. `vercel ls` - Find the deployment URL
+2. `vercel inspect <url>` - Check deployment status and build logs
+3. `vercel logs <url>` - View runtime logs
+4. Compare env vars: `vercel env pull` and check `.env.local`
+
+#### Tips
+
+- Use `gh` and `vercel` CLIs to debug without leaving the terminal
+- Check CI logs before making blind fixes
+- Vercel deployments are blocked until GitHub Actions pass (configured in vercel.json)
+- Pre-commit/pre-push hooks run the same checks as CI - if they pass locally, CI should pass too