Vibery CLI

Production-ready CLI for installing and managing Vibery boilerplate - Astro + Hono + Cloudflare stack with Claude Code integration

Features

• 🚀 One-command setup - Create production-ready websites in minutes
• 🔄 Modular installation - Choose Full Stack, Stack Only, or Claude Team Only
• 📦 Component marketplace - App-store model for managing agents/skills/commands
• 🎨 Smart presets - Solopreneur-focused (tech, marketing, design) or custom
• ☁️ Cloudflare automation - Auto-create D1, KV, R2, Pages resources
• 🤖 Claude Code team - Pre-configured agents, commands, and 40+ skills
• 🔒 Safe updates - Protected file patterns, automatic backups, rollback support
• 📧 Email integration - Resend or SMTP configuration
• 🗄️ Database options - Cloudflare D1 or Astra DB
• 🛡️ Security-first - Credential sanitization, path validation, retry logic

Quick Start

One-Command Setup

# Full-stack project ready in 60 seconds
npx vibery-cli new my-app -y && cd my-app && npx vibery-cli setup

# Quick prototype (minimal components)
npx vibery-cli new prototype --preset minimal -y && cd prototype

# Claude team only (for existing projects)
npx vibery-cli new --claude-only my-project

Verify Everything Works

npx vibery-cli doctor --fix        # Auto-fix common issues
npm run test:cloudflare            # Test Cloudflare connection
npm run validate:env               # Validate .env file

Installation

Option 1: Use directly (no install needed)

npx vibery-cli new my-app

Option 2: Install globally

npm install -g vibery-cli
vibery new my-app

Commands

vibery new <dir> [options]

Create a new Vibery project.

Options:

• --full - Install full stack (Astro + Hono + Cloudflare + Claude team) [default]
• --stack-only - Install stack only (no .claude/)
• --claude-only - Install Claude team directory only
• --preset <preset> - Component preset (minimal, solopreneur-tech, solopreneur-marketing, solopreneur-design, full)
• --version <version> - Install specific version
• -y, --yes - Skip prompts and use defaults
• -f, --force - Overwrite existing directory

Examples:

vibery new my-app
vibery new my-app --full
vibery new my-app --stack-only
vibery new my-app --preset solopreneur-tech
vibery new my-app --claude-only --version v1.2.0

Component Presets:

• minimal (~500KB) - Core agents only (planner, tester, code-reviewer, debugger, git-manager)
• solopreneur-tech (~3.5MB) - Full-stack dev (Cloudflare, Next.js, auth, databases) [default]
• solopreneur-marketing (~4MB) - Content creation, copywriting, design, social media
• solopreneur-design (~3.8MB) - UI/UX design, prototyping, visual content
• full (~10MB) - Everything (all agents, skills, commands)

vibery update [options]

Update existing Vibery project to the latest version.

Options:

• --version <version> - Update to specific version
• --dry-run - Show what would be updated without modifying files
• --claude-only - Update only .claude/ directory
• --stack-only - Update only stack files (no .claude/)
• -f, --force - Force update, overwrite conflicts

Examples:

vibery update
vibery update --dry-run
vibery update --version v1.3.0

vibery setup

Run interactive setup wizard to configure your project.

This command will:

• Configure Cloudflare credentials
• Auto-create Cloudflare resources (D1, KV, R2, Pages)
• Set up database (D1 or Astra DB)
• Configure email provider (Resend or SMTP)
• Generate .env file with all credentials

Example:

vibery setup

vibery deploy [options]

Deploy to Cloudflare Pages.

Options:

• --preview - Deploy to preview environment
• --production - Deploy to production environment
• --branch <branch> - Deploy specific branch

Examples:

vibery deploy --production
vibery deploy --preview
vibery deploy --branch feature-x

vibery doctor [options]

Run diagnostics to check project health and validate configuration.

Options:

• --fix - Attempt to auto-fix common issues

Checks:

• Node.js version
• Project structure
• .env file completeness and format
• Cloudflare credentials validity
• Database configuration
• Wrangler CLI installation
• Dependencies installation
• wrangler.jsonc syntax and bindings

Examples:

vibery doctor                # Run diagnostics
vibery doctor --fix          # Run diagnostics and auto-fix issues

vibery components (or vibery c)

Manage Claude Code components like apps on your phone.

Subcommands:

• list (or ls) - List components (progressive disclosure)
  • --preset <name> - Show components in specific preset
  • --detailed - Show detailed installed components
• search [query] - Search available components
• info <name> - Show component details
• install <name> - Install a component
• remove <name> (or rm) - Remove a component
• presets - List available presets
• preset <name> - Install a preset
• update-registry - Scan project and update component registry

Examples:

# List what you have
vibery components:list

# Search for auth-related components
vibery components:search auth

# Get details about a component
vibery components:info better-auth

# Install a component
vibery components:install better-auth

# Remove a component
vibery components:remove document-skills

# Switch to marketing preset
vibery components:preset solopreneur-marketing

Component Types:

• Agents - Specialized AI agents (planner, tester, code-reviewer, etc.)
• Skills - Domain knowledge & tools (better-auth, cloudflare, nextjs, etc.)
• Commands - Slash commands (/plan, /cook, /test, etc.)
• Workflows - Orchestration rules & development protocols

Why Component Marketplace?

• Start lean - Install only what you need (~500KB minimal vs ~10MB full)
• Cost-optimized - Smaller context = lower token costs
• Discoverable - Browse & search like VSCode extensions
• Flexible - Mix presets + install individual components

Project Structure

The CLI generates projects with the following structure:

my-app/
├── .claude/                  # Claude Code configuration (optional)
│   ├── agents/
│   ├── commands/
│   └── skills/
├── src/                      # Application source code
├── public/                   # Static assets
├── migrations/               # Database migrations
├── user-content/             # User-managed content (protected from updates)
├── .env                      # Environment variables (protected)
├── wrangler.jsonc            # Cloudflare Workers configuration
└── package.json              # Project dependencies

Workflow Examples

🚀 Workflow 1: Solo Tech Founder (Quickest)

# Create minimal project (500KB, 5 core agents)
npx vibery-cli new my-saas --preset minimal -y
cd my-saas

# Verify setup
npx vibery-cli doctor

# Start coding immediately
npm run dev

💼 Workflow 2: Full-Stack Solopreneur

# Create with tech stack preset (3.5MB, 22 components)
npx vibery-cli new my-app --preset solopreneur-tech
cd my-app

# Auto-configure Cloudflare (D1, KV, R2, Pages)
npx vibery-cli setup

# Validate everything
npx vibery-cli doctor --fix
npm run test:cloudflare

# Deploy
npx vibery-cli deploy --production

📝 Workflow 3: Marketing/Content Creator

# Marketing preset (4MB, copywriter + design skills)
npx vibery-cli new content-site --preset solopreneur-marketing
cd content-site

# Browse components
npx vibery-cli components list --preset solopreneur-marketing

# Add specific tools
npx vibery-cli components install gemini-image-gen

# Deploy preview
npx vibery-cli deploy --preview

🔧 Workflow 4: Add to Existing Project

# Install Claude team only (no stack changes)
npx vibery-cli new --claude-only my-existing-project
cd my-existing-project

# Browse and install what you need
npx vibery-cli components list
npx vibery-cli components search auth
npx vibery-cli components install better-auth

# Check installed
npx vibery-cli components list --detailed

🔍 Workflow 5: Troubleshooting

# Health check with auto-fix
npx vibery-cli doctor --fix

# Validate configuration
npm run validate:env          # Check .env file
npm run test:cloudflare       # Test Cloudflare API
npm run check:deps            # Verify dependencies

# Update to latest
npx vibery-cli update

# Rollback if needed
npx vibery-cli update --rollback

🧩 Workflow 6: Component Exploration

# Progressive discovery (start simple)
npx vibery-cli components list                    # See 5 presets
npx vibery-cli components list --preset minimal   # Drill into preset
npx vibery-cli components search cloudflare       # Search by keyword
npx vibery-cli components show nextjs             # Get details

# Install selectively
npx vibery-cli components install docker
npx vibery-cli components install gemini-vision

🎯 Quick One-Liners

# Full stack ready in 60 seconds
npx vibery-cli new my-app -y && cd my-app && npx vibery-cli setup

# Quick prototype
npx vibery-cli new prototype --preset minimal -y && cd prototype

# Health check everything
npx vibery-cli doctor --fix && npm run test:cloudflare

Protected Files

The following files and directories are protected from updates:

• .env* - Environment variables
• .wrangler/ - Wrangler working directory
• node_modules/ - Dependencies
• dist/ - Build output
• .astro/ - Astro cache
• user-content/** - User-managed content
• .claude/agents/custom-* - Custom Claude agents
• .claude/commands/custom-* - Custom Claude commands
• .claude/skills/custom-* - Custom Claude skills
• public/uploads/** - User uploads

Configuration

User configuration is stored in ~/.vibery/config.json.

Backups are automatically created in ~/.vibery/backups/ before updates (keeps last 3 backups).

Development

# Install dependencies
npm install

# Development mode with watch
npm run dev

# Build
npm run build

# Type check
npm run type-check

# Run tests
npm test

Architecture

Core Libraries

• @clack/prompts - Interactive CLI prompts
• @octokit/rest - GitHub API client for downloading releases
• cloudflare - Cloudflare API SDK
• commander - CLI argument parsing
• fs-extra - Enhanced file operations
• ignore - Gitignore-style pattern matching
• tar - Backup/restore functionality
• semver - Version comparison
• zod - Schema validation

Key Features

1. Modular Installation - Choose between Full Stack, Stack Only, or Claude Team Only
2. Protected File Patterns - Custom files are never overwritten during updates
3. Automatic Backups - Every update creates a backup (rollback capability)
4. Cloudflare Integration - Auto-create D1, KV, R2, and Pages resources
5. Interactive Setup - Guided wizard for all configuration
6. Conflict Detection - Warns about conflicts before applying updates
7. Version Management - Install specific versions or update to latest

Security

Vibery CLI implements multiple security measures:

• ✅ Credential sanitization - Tokens/passwords never logged
• ✅ Path validation - Prevents path traversal attacks
• ✅ Zip slip protection - Validates archive entries
• ✅ Resource rollback - Cleans up on Cloudflare failures
• ✅ Retry logic - Handles rate limits and network errors

See SECURITY_FIXES_SUMMARY.md for details.

Troubleshooting

Common Issues

1. "Invalid Cloudflare credentials"

# Verify credentials
vibery doctor

# Recreate API token with correct permissions:
# Account:Read + D1:Edit + KV:Edit + R2:Edit + Pages:Edit

2. "Project already exists"

# Use --force to overwrite
vibery new my-app --force

3. "Update conflicts detected"

# Preview changes first
vibery update --dry-run

# Apply update (creates backup automatically)
vibery update

4. "GitHub rate limit exceeded"

# Wait for rate limit reset (shown in error)
# Or authenticate with GitHub token:
export GITHUB_TOKEN=ghp_...

Debug Mode

Enable detailed logging:

# Set DEBUG environment variable
DEBUG=1 vibery new my-app

# Or use --debug flag
vibery new my-app --debug

Utility Scripts

Vibery CLI includes utility scripts for testing and validation:

Test Cloudflare Connection

pnpm run test:cloudflare
# Or: node scripts/test-cloudflare.ts

Tests your Cloudflare API connection and validates:

• API token validity
• D1 database access
• KV namespace access
• R2 bucket access

Validate Environment File

pnpm run validate:env
# Or: node scripts/validate-env.ts

Checks .env file for:

• Required variables presence
• Format validation (account IDs, UUIDs, tokens)
• Placeholder detection
• Optional variables (with warnings)

Check Dependencies

pnpm run check:deps
# Or: node scripts/check-deps.ts

Verifies project dependencies:

• package.json existence
• node_modules installation
• Critical dependencies (astro, hono, wrangler)
• Outdated packages
• Package manager (pnpm) availability
• Lock file presence

Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

License

MIT © Vibery

Links

• Documentation
• GitHub Repository
• NPM Package

Support

• 📧 Email: [email protected]
• 🐛 Issues: https://github.com/vibery-studio/vibery-boilerplate/issues