/webflow-cli-troubleshooter

name: webflow-cli:troubleshooter
description: Diagnose and fix Webflow CLI issues including installation problems, authentication failures, build errors, and bundle problems. Uses CLI diagnostic flags (--version, --help, --verbose, --debug-bundler) for troubleshooting.

Webflow CLI Troubleshooter

Diagnose and resolve Webflow CLI issues with diagnostic commands and automated fixes.

Important Note

**ALWAYS use Bash tool for all diagnostic operations:**

• Execute diagnostic commands via Bash tool
• Use Read tool to examine configuration files
• Verify CLI installation: `webflow --version`
• Check authentication: `webflow auth login` (if needed)
• Use CLI diagnostic flags: `--verbose`, `--debug-bundler`, `--help`
• DO NOT use Webflow MCP tools for CLI workflows
• All CLI commands require proper descriptions (not context parameters)

**Package Manager Detection:**

• Check for lock files: `package-lock.json` (npm), `pnpm-lock.yaml` (pnpm), `yarn.lock` (yarn)
• If no lock file found, ask user which package manager to use (npm/pnpm/yarn)
• Use detected package manager for all install/build commands

Instructions

Phase 1: Issue Identification

1. **Ask user to describe issue**: What command failed or what error occurred 2. **Determine error category**:

• CLI not installed or wrong version
• Authentication failed
• Build/bundle failed
• Command not recognized

3. **Capture error message**: Get exact error output

Phase 2: Run Diagnostics

4. **Check CLI installation**: Run `webflow --version` 5. **Check authentication**: Run `webflow auth login` if needed 6. **Run command with --verbose**: Execute failed command with `--verbose` flag for detailed output 7. **Use --debug-bundler** (if bundle issue): Run with `--debug-bundler` flag to see bundler config 8. **Check --help**: Run `webflow <command> --help` to verify command syntax

Phase 3: Analyze & Fix

9. **Identify root cause**: Parse error messages and diagnostic output 10. **Present fix**: Show specific solution based on CLI error 11. **Apply fix**: Execute fix commands 12. **Verify**: Re-run original command to confirm resolution

Examples

Example 1: CLI Not Installed

**User prompt:**

Getting "webflow: command not found"

**Diagnostics:**

🔍 Checking CLI Installation

Executing: webflow --version

Error: bash: webflow: command not found

❌ Webflow CLI not installed

**Fix:**

📋 Fix: Install Webflow CLI

Executing: npm install -g @webflow/cli

✓ CLI installed

Verifying...
Executing: webflow --version

Output: @webflow/cli/1.5.2

✅ Issue resolved

Example 2: Build Failed

**User prompt:**

Build is failing but I don't know why

**Diagnostics:**

🔍 Running Build with Diagnostics

Executing: webflow library bundle --verbose

Output:
[verbose] Loading webflow.json
[verbose] Found library config
[verbose] Building components from ./src/**/*.webflow.tsx
[verbose] Running bundler
Error: Failed to resolve import './missing-file.ts'

❌ Build failed: Missing import file

**Fix:**

📋 Fix: Missing Import

Issue: Component imports './missing-file.ts' which doesn't exist

Solutions:
1. Create the missing file
2. Fix the import path
3. Remove the import if not needed

Check your component imports and ensure all files exist.

Example 3: Bundle Configuration Issue

**User prompt:**

Bundle is failing with webpack errors

**Diagnostics:**

🔍 Checking Bundle Configuration

Executing: webflow library bundle --debug-bundler

Output:
[debug-bundler] Final bundler configuration:
{
  "entry": "./src/Component.tsx",
  "output": {
    "path": "/dist",
    "filename": "bundle.js"
  },
  "resolve": {
    "extensions": [".ts", ".tsx", ".js"]
  }
}

Error: Module not found: Can't resolve 'styled-components'

❌ Bundle failed: Missing dependency

**Fix:**

📋 Fix: Install Missing Dependency

Executing: npm install styled-components

✓ Dependency installed

Retrying bundle...
Executing: webflow library bundle

✓ Bundle created successfully

✅ Issue resolved

Guidelines

CLI Diagnostic Commands

**Version Check:**

webflow --version
# or
webflow -V

**Command Help:**

webflow --help                    # General help
webflow library --help            # Library commands help
webflow library bundle --help     # Specific command help

**Verbose Output:**

# Add --verbose to any command for detailed debugging
webflow library bundle --verbose
webflow cloud deploy --verbose
webflow extension bundle --verbose

**Debug Bundler:**

# Show final bundler configuration
webflow library bundle --debug-bundler
webflow extension bundle --debug-bundler

Common Issues & Fixes

**Issue: CLI Not Found**

• **Diagnostic:** `webflow --version` fails
• **Fix:** `npm install -g @webflow/cli`
• **Verify:** `webflow --version` shows version

**Issue: Wrong CLI Version**

• **Diagnostic:** `webflow --version` shows old version
• **Fix:** `npm update -g @webflow/cli`
• **Verify:** Latest version installed

**Issue: Command Not Recognized**

• **Diagnostic:** "Unknown command" error
• **Fix:** Check command with `webflow --help`
• **Verify:** Use correct command syntax

**Issue: Authentication Failed**

• **Diagnostic:** "Not authenticated" error
• **Fix:** `webflow auth login`
• **Verify:** Authentication succeeds

**Issue: Build Failed**

• **Diagnostic:** Run with `--verbose` flag
• **Fix:** Fix errors shown in verbose output
• **Verify:** Build succeeds

**Issue: Bundle Configuration Error**

• **Diagnostic:** Run with `--debug-bundler` flag
• **Fix:** Adjust bundler config in webflow.json
• **Verify:** Bundle succeeds

**Issue: Missing Dependencies**

• **Diagnostic:** "Module not found" errors
• **Fix:** `npm install` or install specific package
• **Verify:** Build/bundle succeeds

**Issue: Corrupted node_modules**

• **Diagnostic:** Unexplained build failures
• **Fix:** `rm -rf node_modules && npm install`
• **Verify:** Build succ