builder-doctor

A CLI tool for Builder.io diagnostics.

Installation

npm install -g builder-doctor

Or run directly with npx:

npx builder-doctor

Usage

builder-doctor [options] [commands]

Options

• --verbose - Show detailed output for each check
• --source <owner/repo> - Override the install source repository for install-skill, skills, and install-plugin
• --agent <name> - Set the target agent folder for install-skill (e.g. github -> .github, claude -> .claude). Defaults to .builder
• BUILDER_SKILLS_SOURCE=<owner/repo> - Environment variable to set the default source repository (overridden by --source)
• --help, -h - Show help message

Running Default Checks

Running without any command will execute both network and rules checks:

npx builder-doctor
npx builder-doctor --verbose  # with detailed output

Displaying Help

To view the help message:

npx builder-doctor help
npx builder-doctor --help
npx builder-doctor -h

Commands

network

Check connectivity to Builder.io services.

npx builder-doctor network

The tool performs diagnostic checks for valid HTTP or ping responses to test network connectivity to:

• firestore.googleapis.com
• firebasestorage.googleapis.com
• identitytoolkit.googleapis.com
• builder.io (Website)
• api.builder.io
• builder.io (Web application)
• cdn.builder.io (Content Network)
• *.builder.codes
• *.builder.my
• builderio.xyz (Cloud Containers)
• 34.136.119.149 (Static IP address used by Builder.io)

The tool cannot verify connectivity to (but you should):

• *.fly.dev

rules

Analyze your Builder.io rules configuration.

npx builder-doctor rules

The tool analyzes your .builderrules, agents.md, and rules in .builder/rules or .cursor/rules. Recommendations are made to:

• Find where there are too many rules being applied at once causing the AI to ignore some rules
• Detect SKILL.md files in incorrect locations (should be in .builder/skills)
• Detect AGENTS.md and CLAUDE.md files with conflicting content
• Common missing front matter like description where needed
• Overuse of alwaysApply
• Rule files with incorrect extensions (should be .mdc instead of .md, except for RULE.md)
• Common incorrect namings of agents.md and .builderrules (including .builderrule and .builderules)

setup

Run the Builder.io agent to analyze your project and provide setup instructions.

npx builder-doctor setup

This command uses the Builder.io agent to review your project and provide:

• Setup commands to install dependencies
• Dev commands to start the development server

The output is brief and formatted for easy reading.

env

Display all environment variables sorted alphabetically.

npx builder-doctor env
npx builder-doctor env --verbose  # shows count of variables

Outputs all environment variables in NAME=value format, one per line, sorted alphabetically. Useful for debugging environment configuration issues.

install-skill

Install a skill from https://github.com/BuilderIO/builder-agent-skills into .builder/skills/<skill-name>.

You can use --source or the environment variable BUILDER_SKILLS_SOURCE to override the source of skills/plugins.

Use --agent <name> to install into a different agent folder (e.g. .github, .claude, .cursor) instead of the default .builder.

npx builder-doctor install-skill skill-creator
npx builder-doctor install-skill skill-a skill-b
npx builder-doctor install-skill skill-creator --agent github   # installs to .github/skills/skill-creator
npx builder-doctor install-skill skill-creator --agent claude   # installs to .claude/skills/skill-creator

If files already exist for that skill, they are overwritten. Multiple skills can be installed at once.

skills

List available skills from https://github.com/BuilderIO/builder-agent-skills.

npx builder-doctor skills

Only folders that contain a SKILL.md file are included in the output.

install-plugin

Install a plugin from https://github.com/BuilderIO/builder-agent-skills.

npx builder-doctor install-plugin my-plugin

Plugin contents are extracted into the .builder root (for example: skills, agents, rules, etc).

mcp

Add or remove the Builder MCP server entry in an agent's MCP configuration file.

npx builder-doctor mcp add <agent>
npx builder-doctor mcp remove <agent>

Supported agents and the file each one writes to:

| Agent | File | | ------------ | ------------------------------------- | | claude | ~/.claude/settings.local.json | | cursor | ~/.cursor/mcp.json | | copilot | .vscode/mcp.json (project-local) | | code_puppy | ~/.code_puppy/mcp_servers.json | | wibey | ~/.wibey/mcp.json and ~/.vscode/mcp.json | | _(omitted)_ | mcp.json (project-local) |

add creates the file (and any missing parent directories) if it doesn't exist, and merges the builder-mcp entry into it without disturbing other settings. remove deletes only the builder-mcp entry.

After an add, your Builder.io authentication is checked by running npx --yes "@builder.io/dev-tools@latest" auth status (logged as Checking Builder.io Authentication....). If you're already authenticated it logs Builder.io authenticated. along with the status details and continues. Otherwise you are prompted Authenticate with Builder.io? (Y/n), and unless you answer n it runs npx --yes "@builder.io/dev-tools@latest" auth to sign in. The check and prompt are skipped when not running in an interactive terminal.

npx builder-doctor mcp add claude        # ~/.claude/settings.local.json
npx builder-doctor mcp add cursor        # ~/.cursor/mcp.json
npx builder-doctor mcp add copilot       # .vscode/mcp.json
npx builder-doctor mcp add code_puppy    # ~/.code_puppy/mcp_servers.json
npx builder-doctor mcp add wibey         # ~/.wibey/mcp.json and ~/.vscode/mcp.json
npx builder-doctor mcp add               # ./mcp.json
npx builder-doctor mcp remove claude     # remove from Claude

Examples

builder-doctor                  # Run network and rules checks
builder-doctor network          # Run only network checks
builder-doctor rules            # Run only rules checks
builder-doctor setup            # Get project setup instructions
builder-doctor env              # Display environment variables
builder-doctor install-skill skill-creator                       # Install a skill into .builder/skills
builder-doctor install-skill skill-creator --agent github         # Install a skill into .github/skills
builder-doctor install-skill skill-creator --agent claude         # Install a skill into .claude/skills
builder-doctor install-skill skill-creator --source myorg/myrepo # Install a skill from a custom source
builder-doctor skills                                            # List available skills (requires SKILL.md)
builder-doctor skills --source myorg/myrepo                      # List available skills from a custom source
BUILDER_SKILLS_SOURCE=myorg/myrepo builder-doctor skills         # Use env var as the default source
builder-doctor install-plugin my-plugin                          # Install a plugin into .builder
builder-doctor install-plugin my-plugin --source myorg/myrepo    # Install a plugin from a custom source
builder-doctor mcp add claude                                    # Add Builder MCP entry to ~/.claude/settings.local.json
builder-doctor mcp add cursor                                    # Add Builder MCP entry to ~/.cursor/mcp.json
builder-doctor mcp add copilot                                   # Add Builder MCP entry to .vscode/mcp.json
builder-doctor mcp add code_puppy                                # Add Builder MCP entry to ~/.code_puppy/mcp_servers.json
builder-doctor mcp add wibey                                     # Add Builder MCP entry to ~/.wibey/mcp.json and ~/.vscode/mcp.json
builder-doctor mcp add                                           # Create or update a local mcp.json
builder-doctor mcp remove claude                                 # Remove the Builder MCP entry for Claude
builder-doctor --verbose                                         # Run all checks with detailed output