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 succeeds

Error Handling

CLI Not Installed:

❌ Webflow CLI Not Found

Install:
npm install -g @webflow/cli

Verify:
webflow --version

Docs: https://developers.webflow.com/cli

Authentication Required:

❌ Authentication Failed

Fix:
webflow auth login

Follow browser prompts to authenticate

Build/Bundle Failed:

❌ Build Failed

Run with diagnostics:
webflow library bundle --verbose --debug-bundler

This shows:
- Detailed build steps
- Import resolution
- Bundler configuration
- Exact error location

Fix the errors shown in output

Unknown Error:

❌ Unknown Issue

Gather info:
1. What command are you running?
2. Run command with --verbose flag
3. Check command syntax with --help
4. Share full error output

This helps identify the specific problem

File Operations

Reading Config Files:

# View webflow.json
Read: webflow.json

# View package.json
Read: package.json

# View build output
Read: dist/

Discovering Files:

# Find config files
Glob: **/webflow.json

# Find components
Glob: src/**/*.webflow.tsx

# Find logs
Glob: **/*.log

Best Practices

Always Start With:

1. Check CLI version: webflow --version
2. Check command syntax: webflow <command> --help
3. Run with verbose: Add --verbose flag

For Build/Bundle Issues:

1. Use --verbose for detailed output
2. Use --debug-bundler to see config
3. Check import paths
4. Verify dependencies installed

For Authentication Issues:

1. Run webflow auth login
2. Follow browser prompts
3. Verify workspace access

For Installation Issues:

1. Check Node.js version: node --version
2. Install CLI globally: npm install -g @webflow/cli
3. Verify installation: webflow --version

Quick Reference

Workflow: identify → diagnose → fix → verify

Diagnostic Flags:

• --version / -V - Check CLI version
• --help / -h - Show command help
• --verbose - Detailed debugging output
• --debug-bundler - Show bundler config

Common Fixes:

• Not installed → npm install -g @webflow/cli
• Wrong version → npm update -g @webflow/cli
• Auth failed → webflow auth login
• Build failed → Check --verbose output
• Bundle error → Check --debug-bundler output
• Missing deps → npm install

Documentation: https://developers.webflow.com/cli