builderos-cli 2.0.0

package/.builderos

@@ -0,0 +1,7 @@
+{
+  "initialized": true,
+  "version": "2.0.0",
+  "timestamp": "2026-01-14T14:40:57.408Z",
+  "architecture": "api-based",
+  "cli_version": "2.0.0"
+}

package/.mcp.json

@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "builder-os": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@builderos/mcp-client"
+      ],
+      "env": {
+        "BUILDEROS_API_URL": "http://builder-os.test"
+      }
+    }
+  }
+}

package/PUBLISH.md

@@ -0,0 +1,182 @@
+# Publishing @builderos/cli to npm
+
+## Prerequisites
+
+1. npm account (create at https://www.npmjs.com/signup)
+2. Verified email address
+3. npm login credentials
+
+## Publishing Steps
+
+### 1. Test Locally
+
+```bash
+cd /Users/audilu/next/builder-os/cli
+
+# Test the CLI
+node index.js --help
+node index.js init --api-url=http://builder-os.test
+
+# Verify package.json
+cat package.json
+```
+
+### 2. Login to npm
+
+```bash
+npm login
+```
+
+Enter your:
+- Username
+- Password
+- Email (must be verified)
+- OTP (if 2FA enabled)
+
+### 3. Publish
+
+```bash
+cd /Users/audilu/next/builder-os/cli
+npm publish --access public
+```
+
+**Important**: Use `--access public` because scoped packages (@builderos/cli) are private by default.
+
+### 4. Verify Publication
+
+```bash
+# Check on npm
+npm view @builderos/cli
+
+# Test installation
+cd /tmp/test-npm
+npx @builderos/cli --help
+```
+
+## Version Updates
+
+When making changes:
+
+### 1. Update Version
+
+```bash
+# Patch (2.0.0 → 2.0.1)
+npm version patch
+
+# Minor (2.0.0 → 2.1.0)
+npm version minor
+
+# Major (2.0.0 → 3.0.0)
+npm version major
+```
+
+### 2. Publish Update
+
+```bash
+npm publish --access public
+```
+
+## Quick Reference
+
+```bash
+# Full publication workflow
+cd /Users/audilu/next/builder-os/cli
+npm version patch          # Update version
+npm publish --access public # Publish to npm
+```
+
+## Troubleshooting
+
+### "You must be logged in to publish packages"
+
+```bash
+npm login
+```
+
+### "You do not have permission to publish"
+
+Make sure you're logged in with the correct account:
+
+```bash
+npm whoami
+```
+
+### "Package name already exists"
+
+This means @builderos/cli is already taken. Choose a different name in package.json.
+
+### "402 Payment Required"
+
+Scoped packages need `--access public`:
+
+```bash
+npm publish --access public
+```
+
+## Post-Publication
+
+### Test Installation
+
+```bash
+# In a clean directory
+cd /tmp/test-install
+npx @builderos/cli init --api-url=http://builder-os.test
+```
+
+### Update Documentation
+
+Update README.md and other docs to reference the published package.
+
+### Announce
+
+Let users know the package is available:
+- README.md
+- Documentation
+- Release notes
+
+## Package Info
+
+After publishing, view package info:
+
+```bash
+npm view @builderos/cli
+npm view @builderos/cli versions
+npm view @builderos/cli dist-tags
+```
+
+## Unpublishing (Emergency Only)
+
+⚠️ **Warning**: Can only unpublish within 72 hours. After that, version is permanent.
+
+```bash
+# Unpublish specific version
+npm unpublish @builderos/cli@2.0.0
+
+# Unpublish entire package (use with extreme caution)
+npm unpublish @builderos/cli --force
+```
+
+## Best Practices
+
+1. **Test before publishing** - Always test locally first
+2. **Semantic versioning** - Follow semver (MAJOR.MINOR.PATCH)
+3. **Changelog** - Keep a CHANGELOG.md
+4. **Git tags** - Tag releases in git
+5. **CI/CD** - Consider automated publishing
+6. **Security** - Enable 2FA on npm account
+
+## Package Links
+
+After publishing:
+
+- npm: https://www.npmjs.com/package/@builderos/cli
+- unpkg: https://unpkg.com/@builderos/cli
+- jsdelivr: https://cdn.jsdelivr.net/npm/@builderos/cli
+
+---
+
+Ready to publish? Run:
+
+```bash
+cd /Users/audilu/next/builder-os/cli && npm publish --access public
+```

package/README.md

@@ -0,0 +1,333 @@
+# @builderos/cli
+
+BuilderOS CLI - Initialize BuilderOS in any project without requiring local code.
+
+## 🚀 Quick Start
+
+```bash
+# 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.
+
+```bash
+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:**
+
+```bash
+# 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.
+
+```bash
+npx @builderos/cli update [options]
+```
+
+**Options:**
+- `--api-url=<url>` - BuilderOS API URL (default: `http://builder-os.test`)
+
+**Example:**
+
+```bash
+# 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`
+
+```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
+
+```bash
+# Developer has BuilderOS running locally at builder-os.test
+cd ~/projects/my-app
+npx @builderos/cli init
+```
+
+### Remote Team Collaboration
+
+```bash
+# 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
+
+```bash
+# Automated setup in CI
+npx @builderos/cli init --api-url=$BUILDEROS_API_URL --force
+```
+
+### Multiple Environments
+
+```bash
+# 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
+
+```bash
+# 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:
+```gitignore
+# .mcp.json
+# .claude/
+```
+
+### 2. Commit
+
+```bash
+git add .mcp.json .claude/ .gitignore
+git commit -m "Add BuilderOS configuration"
+git push
+```
+
+### 3. Team Members
+
+After cloning:
+```bash
+# 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:
+
+```bash
+# 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`:
+
+```bash
+npx @builderos/cli init
+```
+
+## 🐛 Troubleshooting
+
+### CLI not found
+
+```bash
+# Make sure you're online
+# npx will download the package
+
+# Or install globally
+npm install -g @builderos/cli
+builderos init
+```
+
+### API connection failed
+
+```bash
+# 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
+
+```bash
+# Verify skills directory
+ls -la .claude/skills/
+
+# Re-download skills
+npx @builderos/cli update --api-url=http://builder-os.test
+```
+
+### MCP not connecting
+
+```bash
+# Verify .mcp.json
+cat .mcp.json
+
+# Restart VSCode completely
+# Cmd+Q, not just reload
+```
+
+## 📦 Publishing to npm
+
+When BuilderOS is ready for production:
+
+```bash
+cd /Users/audilu/next/builder-os/cli
+npm login
+npm publish --access public
+```
+
+Then users can use:
+
+```bash
+npx @builderos/cli init
+```
+
+## 🔗 Related
+
+- [@builderos/mcp-client](../mcp-client/) - Lightweight MCP HTTP client
+- [use-builderos.sh](../scripts/use-builderos.sh) - Local development script
+- [REMOTE-USAGE.md](../REMOTE-USAGE.md) - Remote usage guide
+
+## 📄 License
+
+MIT
+
+---
+
+**BuilderOS CLI** - Initialize Anywhere, Anytime

package/index.js

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+
+/**
+ * BuilderOS CLI
+ *
+ * Initialize BuilderOS in any project without requiring local code.
+ * Works purely through BuilderOS HTTP API.
+ *
+ * Usage:
+ *   npx @builderos/cli init [options]
+ *   npx @builderos/cli update [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
+ *   --help              Show help
+ */
+
+import { mkdir, writeFile, readFile, access } from 'fs/promises';
+import { join } from 'path';
+import { constants } from 'fs';
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+
+// Default options
+const options = {
+  apiUrl: process.env.BUILDEROS_API_URL || 'http://builder-os.test',
+  force: false,
+  mcpOnly: false,
+  skillsOnly: false,
+  help: false,
+};
+
+// Check if first arg is help or no command
+const command = args[0];
+if (!command || command === '--help' || command === '-h') {
+  options.help = true;
+}
+
+// Parse options
+for (const arg of args) {
+  if (arg.startsWith('--api-url=')) {
+    options.apiUrl = arg.split('=')[1];
+  } else if (arg === '--force') {
+    options.force = true;
+  } else if (arg === '--mcp-only') {
+    options.mcpOnly = true;
+  } else if (arg === '--skills-only') {
+    options.skillsOnly = true;
+  } else if (arg === '--help' || arg === '-h') {
+    options.help = true;
+  }
+}
+
+// Show help
+if (options.help) {
+  console.log(`
+BuilderOS CLI v2.0.0
+
+Usage:
+  npx @builderos/cli init [options]
+  npx @builderos/cli update [options]
+
+Commands:
+  init      Initialize BuilderOS in current project
+  update    Update skills from BuilderOS API
+
+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
+  --help, -h          Show this help
+
+Examples:
+  # Initialize with local BuilderOS
+  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 --skills-only
+
+  # Force reinstall
+  npx @builderos/cli init --force
+`);
+  process.exit(0);
+}
+
+// Utility: Check if file exists
+async function fileExists(path) {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Utility: Fetch from API
+async function fetchAPI(endpoint) {
+  try {
+    const url = `${options.apiUrl}${endpoint}`;
+    const response = await fetch(url, {
+      headers: {
+        'Host': 'builder-os.test', // For local nginx-proxy
+      },
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    return await response.json();
+  } catch (error) {
+    console.error(`❌ Error fetching ${endpoint}:`, error.message);
+    return null;
+  }
+}
+
+// Step 1: Create .mcp.json
+async function installMCP() {
+  console.log('1️⃣  Creating .mcp.json (MCP configuration)...');
+
+  const mcpPath = '.mcp.json';
+
+  if (await fileExists(mcpPath)) {
+    const content = await readFile(mcpPath, 'utf-8');
+    if (content.includes('builder-os')) {
+      if (!options.force) {
+        console.log('   ⚠️  builder-os already configured in .mcp.json');
+        console.log('   Use --force to overwrite');
+        return;
+      }
+    }
+  }
+
+  // Always use remote mode (npx @builderos/mcp-client)
+  // This CLI is meant to be standalone, not requiring local BuilderOS code
+  const mcpConfig = {
+    mcpServers: {
+      'builder-os': {
+        type: 'stdio',
+        command: 'npx',
+        args: ['-y', '@builderos/mcp-client'],
+        env: {
+          BUILDEROS_API_URL: options.apiUrl,
+        },
+      },
+    },
+  };
+
+  await writeFile(mcpPath, JSON.stringify(mcpConfig, null, 2) + '\n');
+  console.log('   ✅ .mcp.json created');
+  console.log(`   🌐 Using remote MCP client with ${options.apiUrl}`);
+}
+
+// Step 2: Download skills from API
+async function installSkills() {
+  console.log('2️⃣  Downloading BuilderOS skills from API...');
+  console.log(`   API URL: ${options.apiUrl}`);
+
+  // Fetch skills list
+  const data = await fetchAPI('/api/skills');
+  if (!data || !data.skills) {
+    console.log('   ❌ Failed to fetch skills list');
+    return;
+  }
+
+  const skills = data.skills;
+  console.log(`   Found ${skills.length} skills`);
+
+  // Create .claude/skills directory
+  const skillsDir = '.claude/skills';
+  await mkdir(skillsDir, { recursive: true });
+
+  let successCount = 0;
+  const failedSkills = [];
+
+  // Download each skill
+  for (const skill of skills) {
+    console.log(`   📥 Downloading: ${skill.slug}`);
+
+    const skillData = await fetchAPI(`/api/skills/${skill.slug}`);
+
+    if (!skillData || !skillData.content) {
+      console.log(`      ⚠️  No content available`);
+      failedSkills.push(skill.slug);
+      continue;
+    }
+
+    // Create skill directory
+    const skillDir = join(skillsDir, skill.slug);
+    await mkdir(skillDir, { recursive: true });
+
+    // Write skill.md
+    const skillPath = join(skillDir, 'skill.md');
+    await writeFile(skillPath, skillData.content);
+
+    console.log(`      ✅ Saved to ${skillDir}/skill.md`);
+    successCount++;
+  }
+
+  console.log('');
+  console.log('==========================================');
+  console.log('  ✅ Skills Download Complete!');
+  console.log('==========================================');
+  console.log('');
+  console.log(`Downloaded: ${successCount}/${skills.length} skills`);
+
+  if (failedSkills.length > 0) {
+    console.log('');
+    console.log('⚠️  Failed to download:');
+    failedSkills.forEach(slug => console.log(`   - ${slug}`));
+  }
+
+  console.log('');
+  console.log(`Skills saved to: ${skillsDir}/`);
+}
+
+// Step 3: Create .builderos marker
+async function createMarker() {
+  console.log('3️⃣  Creating BuilderOS marker...');
+
+  const marker = {
+    initialized: true,
+    version: '2.0.0',
+    timestamp: new Date().toISOString(),
+    architecture: 'api-based',
+    cli_version: '2.0.0',
+  };
+
+  await writeFile('.builderos', JSON.stringify(marker, null, 2) + '\n');
+  console.log('   ✅ Marker created');
+}
+
+// Step 4: Update .gitignore
+async function updateGitignore() {
+  console.log('4️⃣  Updating .gitignore...');
+
+  let gitignoreContent = '';
+
+  if (await fileExists('.gitignore')) {
+    gitignoreContent = await readFile('.gitignore', 'utf-8');
+  }
+
+  let updated = false;
+
+  // Add .mcp.json (commented)
+  if (!gitignoreContent.includes('.mcp.json')) {
+    gitignoreContent += '\n# BuilderOS MCP - Remove comment to share with team\n';
+    gitignoreContent += '# .mcp.json\n';
+    console.log('   ✅ Added .mcp.json to .gitignore (commented)');
+    updated = true;
+  } else {
+    console.log('   ℹ️  .mcp.json already in .gitignore');
+  }
+
+  // Add .claude/ (commented)
+  if (!gitignoreContent.includes('.claude/')) {
+    gitignoreContent += '# Claude Skills - Remove comment to share with team\n';
+    gitignoreContent += '# .claude/\n';
+    console.log('   ✅ Added .claude/ to .gitignore (commented)');
+    updated = true;
+  } else {
+    console.log('   ℹ️  .claude/ already in .gitignore');
+  }
+
+  // Add .builderos
+  if (!gitignoreContent.includes('.builderos')) {
+    gitignoreContent += '.builderos\n';
+    console.log('   ✅ Added .builderos to .gitignore');
+    updated = true;
+  } else {
+    console.log('   ℹ️  .builderos already in .gitignore');
+  }
+
+  if (updated) {
+    await writeFile('.gitignore', gitignoreContent);
+  }
+}
+
+// Main execution
+async function main() {
+  console.log('==========================================');
+  console.log('  BuilderOS CLI v2.0.0');
+  console.log('==========================================');
+  console.log('');
+  console.log(`Command: ${command}`);
+  console.log(`API URL: ${options.apiUrl}`);
+  console.log('');
+
+  try {
+    if (command === 'init') {
+      // Detect current state
+      const hasMCP = await fileExists('.mcp.json');
+      const hasSkills = await fileExists('.claude/skills');
+
+      let mode = 'install';
+      if (options.force) {
+        mode = 'install';
+        console.log('🔄 Force mode: Reinstalling everything...');
+      } else if (options.mcpOnly) {
+        mode = 'mcp-only';
+        console.log('🔧 MCP only mode');
+      } else if (options.skillsOnly) {
+        mode = 'skills-only';
+        console.log('📥 Skills only mode');
+      } else if (!hasMCP && !hasSkills) {
+        mode = 'install';
+        console.log('🆕 New project detected: Installing BuilderOS...');
+      } else if (hasMCP && hasSkills) {
+        mode = 'update';
+        console.log('🔄 BuilderOS already installed: Updating skills...');
+      } else if (hasMCP && !hasSkills) {
+        mode = 'skills-only';
+        console.log('📥 MCP configured: Installing skills...');
+      } else {
+        mode = 'install';
+        console.log('🔧 Partial installation: Completing setup...');
+      }
+
+      console.log('');
+
+      // Execute based on mode
+      if (mode === 'install') {
+        await installMCP();
+        console.log('');
+        await installSkills();
+        console.log('');
+        await createMarker();
+        console.log('');
+        await updateGitignore();
+      } else if (mode === 'update') {
+        await installSkills();
+      } else if (mode === 'mcp-only') {
+        await installMCP();
+        console.log('');
+        await createMarker();
+        console.log('');
+        await updateGitignore();
+      } else if (mode === 'skills-only') {
+        await installSkills();
+      }
+
+      console.log('');
+      console.log('==========================================');
+      console.log('  ✅ BuilderOS Setup Complete!');
+      console.log('==========================================');
+      console.log('');
+      console.log('Next steps:');
+      console.log('');
+      console.log('1. Restart VSCode completely (Cmd+Q, not Reload Window)');
+      console.log('');
+      console.log('2. Reopen this project');
+      console.log('');
+      console.log('3. Test MCP connection:');
+      console.log('   /mcp');
+      console.log('   # Should show: builder-os');
+      console.log('');
+      console.log('4. Test Claude Skills:');
+      console.log('   "What skills do I have?"');
+      console.log('   # Should list available skills');
+      console.log('');
+    } else if (command === 'update') {
+      console.log('🔄 Updating BuilderOS skills...');
+      console.log('');
+      await installSkills();
+      console.log('');
+      console.log('✅ Update complete!');
+    } else {
+      console.log(`❌ Unknown command: ${command}`);
+      console.log('Run "npx @builderos/cli --help" for usage');
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error('');
+    console.error('❌ Error:', error.message);
+    console.error('');
+    console.error('Stack trace:');
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "builderos-cli",
+  "version": "2.0.0",
+  "description": "BuilderOS CLI - Initialize BuilderOS in any project without requiring local code",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "builderos": "./index.js"
+  },
+  "scripts": {
+    "test": "node index.js init --help"
+  },
+  "keywords": [
+    "builderos",
+    "claude",
+    "mcp",
+    "ai",
+    "cli",
+    "developer-tools"
+  ],
+  "author": "BuilderOS",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/builderos/builderos"
+  }
+}