builderos-cli

BuilderOS CLI - Initialize BuilderOS in any project without requiring local code.

🚀 Quick Start

# Initialize BuilderOS in current project
npx builderos-cli init

# Initialize with remote BuilderOS
npx builderos-cli init --api-url=https://api.builderos.com

# Update skills only
npx builderos-cli update

📦 What This Does

This CLI tool:

1. ✅ Creates .mcp.json - MCP configuration for Claude Code
2. ✅ Downloads skills from BuilderOS API to .claude/skills/
3. ✅ Creates .builderos marker file
4. ✅ Updates .gitignore with BuilderOS files (commented for easy sharing)

🌟 Features

• No local BuilderOS code required - Works purely through API
• Supports any API URL - Local testing or remote production
• Smart detection - Automatically detects project state (new/existing)
• Flexible modes - Install, update, MCP-only, or skills-only
• Team-friendly - Easy to share configuration with team

📖 Commands

init

Initialize BuilderOS in current project.

npx builderos-cli init [options]

Options:

• --api-url=<url> - BuilderOS API URL (default: http://builder-os.test)
• --force - Force reinstall even if already configured
• --mcp-only - Only install MCP configuration
• --skills-only - Only download skills

Examples:

# Local development (default)
npx builderos-cli init

# Remote BuilderOS
npx builderos-cli init --api-url=https://api.builderos.com

# Force reinstall
npx builderos-cli init --force

# Only install MCP, skip skills
npx builderos-cli init --mcp-only

# Only download skills, skip MCP
npx builderos-cli init --skills-only

update

Update skills from BuilderOS API.

npx builderos-cli update [options]

Options:

• --api-url=<url> - BuilderOS API URL (default: http://builder-os.test)

Example:

# Update skills from default API
npx builderos-cli update

# Update skills from remote API
npx builderos-cli update --api-url=https://api.builderos.com

🔧 How It Works

Architecture

npx builderos-cli init
    ↓
1. Create .mcp.json
   - Uses npx @builderos/mcp-client
   - No local code dependency
    ↓
2. Download skills from API
   - Fetch /api/skills (list)
   - Fetch /api/skills/{slug} (content)
   - Save to .claude/skills/
    ↓
3. Create .builderos marker
   - Track initialization state
    ↓
4. Update .gitignore
   - Add BuilderOS files (commented)

Generated .mcp.json

{
  "mcpServers": {
    "builder-os": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@builderos/mcp-client"],
      "env": {
        "BUILDEROS_API_URL": "https://api.builderos.com"
      }
    }
  }
}

Key point: Always uses npx @builderos/mcp-client, not local code.

🌍 Use Cases

Local Development

# Developer has BuilderOS running locally at builder-os.test
cd ~/projects/my-app
npx builderos-cli init

Remote Team Collaboration

# Team uses shared BuilderOS at api.builderos.com
cd ~/projects/team-app
npx builderos-cli init --api-url=https://api.builderos.com

CI/CD Pipeline

# Automated setup in CI
npx builderos-cli init --api-url=$BUILDEROS_API_URL --force

Multiple Environments

# Development
npx builderos-cli init --api-url=https://dev.builderos.com

# Staging
npx builderos-cli init --api-url=https://staging.builderos.com

# Production
npx builderos-cli init --api-url=https://api.builderos.com

🎯 Comparison with use-builderos.sh

| Feature | builderos-cli | use-builderos.sh | |---------|----------------|------------------| | Requires local BuilderOS code | ❌ No | ✅ Yes (for script itself) | | Works anywhere | ✅ Yes | ⚠️ Only if script accessible | | npm installable | ✅ Yes | ❌ No | | MCP mode | Remote only | Local + Remote | | Best for | Remote deployment | Local development |

📝 After Installation

1. Restart VSCode

# Quit completely (not just reload)
Cmd+Q (Mac) or Ctrl+Q (Linux/Windows)

2. Reopen Project

Open the project directory in VSCode.

3. Test MCP Connection

/mcp

Should show: builder-os

4. Test Skills

Ask Claude:

What skills do I have?

Should list available BuilderOS skills.

🤝 Team Sharing

To share BuilderOS with your team:

1. Edit .gitignore

Remove # from:

# .mcp.json
# .claude/

2. Commit

git add .mcp.json .claude/ .gitignore
git commit -m "Add BuilderOS configuration"
git push

3. Team Members

After cloning:

# No need to run CLI - files already in repo
# Just restart VSCode
Cmd+Q

Done! BuilderOS works automatically.

🔒 Environment Variables

BUILDEROS_API_URL

Set default API URL:

# Local development
export BUILDEROS_API_URL=http://builder-os.test

# Remote production
export BUILDEROS_API_URL=https://api.builderos.com

Then run without --api-url:

npx builderos-cli init

🐛 Troubleshooting

CLI not found

# Make sure you're online
# npx will download the package

# Or install globally
npm install -g builderos-cli
builderos init

API connection failed

# Check API URL
curl http://builder-os.test/api/skills

# Try with explicit URL
npx builderos-cli init --api-url=http://builder-os.test

Skills not loading

# Verify skills directory
ls -la .claude/skills/

# Re-download skills
npx builderos-cli update --api-url=http://builder-os.test

MCP not connecting

# Verify .mcp.json
cat .mcp.json

# Restart VSCode completely
# Cmd+Q, not just reload

📦 Publishing to npm

When BuilderOS is ready for production:

cd /Users/audilu/next/builder-os/cli
npm login
npm publish --access public

Then users can use:

npx builderos-cli init

🔗 Related

• @builderos/mcp-client - Lightweight MCP HTTP client
• use-builderos.sh - Local development script
• REMOTE-USAGE.md - Remote usage guide

📄 License

MIT

BuilderOS CLI - Initialize Anywhere, Anytime