beste-cli

Official CLI for beste.co - Install premium shadcn components with a single command.

Roadmap: see ROADMAP.md

Table of Contents

• Installation
• Initialize Project
• Add a Component
• Remove a Component
• Self-Healing (Build Fix Loop)
• Catalog Sync
• MCP Tools
• AI Agent Prompts
• Authentication
• Supported Package Managers
• How It Works
• Requirements
• Contributing
• License
• Links

Installation

Install globally to use beste command anywhere:

npm install -g beste-cli

Or use with npx without installation:

npx beste-cli add https://ui.beste.co/r/feature63

Usage

Global flags (all commands):

• --json machine-readable output
• --yes non-interactive mode (no prompts)
• --dry-run preview changes without writing files
• --config-dir <path> override auth/config directory (or set BESTE_HOME_DIR)

1) Initialize Project (Recommended First Step)

beste init

Run this once in a new project. It does everything needed to get started:

• Creates AGENTS.md with AI agent instructions and workflow guide
• Creates .beste/state.json, .beste/mcp.json, .beste/catalog.json
• Initializes shadcn/ui if not already set up (components.json)
• Registers @beste-ui registry in shadcn automatically
• Syncs the full component catalog from beste.co (~800+ components)
• Registers the MCP server in your editor config:
  • .cursor/mcp.json (Cursor)
  • .windsurf/mcp.json (Windsurf)
  • .vscode/mcp.json (VS Code)

Options:

• --dry-run preview changes without writing files
• --force overwrite all generated files (including AGENTS.md)
• --api API-only mode: skip shadcn/ui setup and append to existing AGENTS.md

API-only mode (--api) is useful when you want to add beste-cli to an existing project that already has shadcn/ui configured, or when you only need the MCP server integration without UI components. This mode:

• Skips shadcn/ui initialization
• Skips @beste-ui registry registration
• Appends an "API Integration" section to existing AGENTS.md instead of skipping it
• Still creates .beste/ config files and syncs the catalog

# Use --api flag for existing projects or API-only setups
beste init --api

Add a Component

beste add feature63

Or with a full URL:

beste add https://ui.beste.co/r/feature63

The CLI will:

• ✅ Fetch the component from beste.co
• ✅ Register @beste-ui shadcn registry if not already registered
• ✅ Detect your project structure automatically
• ✅ Install files to the correct location
• ✅ Check for and install missing npm/shadcn dependencies
• ✅ Save demo data to lib/beste/component-data.ts (for AI agents)

Demo data: Every component ships with a *Demo export (e.g. agency10Demo). After beste add, this is automatically extracted and saved to lib/beste/component-data.ts (or src/lib/beste/component-data.ts). Import demo data from there — not directly from the component file:

// ✅ Correct
import { Agency10 } from "@/components/beste/agency10";
import { agency10Demo } from "@/lib/beste/component-data";

<Agency10 {...agency10Demo} />

Remove a Component

beste remove feature63

Self-Healing (Build Fix Loop)

beste heal --check

Apply automatic fixes (missing deps/shadcn hints) and retry build:

beste heal --max-attempts 3

Catalog Sync

Syncs the local component catalog from the beste.co registry:

# Fetch all components (~800+) from beste.co
beste catalog sync

# Fetch metadata for a single component
beste catalog sync navbar30

# Sync from a local JSON file
beste catalog sync --file ./catalog-source.json

# Merge into existing catalog instead of replacing
beste catalog sync --merge

The catalog is stored at .beste/catalog.json and is used by MCP workflows to select the best components for your project.

MCP Tools

MCP (Model Context Protocol) allows AI agents (Cursor, Windsurf, Claude Code, etc.) to discover and call beste-cli tools in a structured way.

After beste init, your editor's MCP config is set up automatically. You can also start the server manually:

beste mcp serve

Available Tools

Core Tools

| Tool | Description | |---|---| | analyze_project | Returns project health, installed components, catalog status | | search_codebase | Searches source files for text, symbols, or patterns | | install_component | Installs a beste component (handles all deps) | | install_components_batch | Installs multiple components in one call with partial-failure reporting | | heal_project | Runs build-check and automatic fix loop for common integration issues | | workflow_setup_landing_page | Plans or installs a full landing page from the catalog |

Advanced Tools (LangChain/LangGraph Integration)

| Tool | Description | |---|---| | component_get_source | Fetches canonical source code to prevent LLM hallucination | | components_ensure | Deterministic batch install with status checking | | project_validate | Unified validation with standardized error reporting | | landing_plan_resolve | Deterministic landing page planning with seed-based consistency | | page_template_generate | Generates correct app/page.tsx with proper import wiring | | component_data_sync | Prevents drift between component props and demo data |

MCP CLI Commands

# List all available tools
beste --json mcp list-tools

# Analyze the current project
beste --json mcp call analyze_project

# Search for a symbol in the codebase
beste --json mcp call search_codebase --args '{"query":"HeroSection","fileGlob":"**/*.tsx"}'

# Install a component via MCP
beste --json mcp call install_component --args '{"component":"navbar30"}'

# Install many components in one call
beste --json mcp call install_components_batch --args '{"components":["hero1","cta1"],"dryRun":true}'

# Run self-healing (check only)
beste --json mcp call heal_project --args '{"checkOnly":true,"maxAttempts":3}'

# Plan a landing page (review before installing)
beste --json mcp call workflow_setup_landing_page --args '{"niche":"saas","style":"modern","mode":"plan"}'

# Apply — install all selected components
beste --json mcp call workflow_setup_landing_page --args '{"niche":"saas","style":"modern","mode":"apply"}'

# Get canonical source code (prevent hallucination)
beste --json mcp call component_get_source --args '{"name":"navbar30"}'

# Ensure multiple components are installed
beste --json mcp call components_ensure --args '{"names":["hero15","cta10","footer5"]}'

# Validate project and check for issues
beste --json mcp call project_validate --args '{"scope":"all"}'

# Auto-fix validation issues
beste --json mcp call project_validate --args '{"scope":"all","fix":true}'

# Generate deterministic landing page plan
beste --json mcp call landing_plan_resolve --args '{"prompt":"modern saas landing page","seed":"my-seed-123"}'

# Generate page template with correct imports
beste --json mcp call page_template_generate --args '{"selectedComponents":[{"section":"hero","component":"hero15"}]}'

# Check component data sync status
beste --json mcp call component_data_sync --args '{"mode":"check"}'

# Update drifted component data
beste --json mcp call component_data_sync --args '{"mode":"update","components":["navbar30"]}'

# === PREMIUM COMPONENTS AUTHENTICATION ===
# For premium components, provide email and licenseKey to bypass local login

# Install premium component with auth
beste --json mcp call install_component --args '{"component":"feature81","email":"[email protected]","licenseKey":"YOUR-LICENSE-KEY"}'

# Batch install premium components
beste --json mcp call components_ensure --args '{"names":["feature81","feature82"],"email":"[email protected]","licenseKey":"YOUR-LICENSE-KEY"}'

# Landing page workflow with auth
beste --json mcp call workflow_setup_landing_page --args '{"niche":"saas","mode":"apply","email":"[email protected]","licenseKey":"YOUR-LICENSE-KEY"}'

PowerShell-safe alternative (recommended on Windows):

beste --json mcp call <tool_name> --args-file ./mcp-args.json

Recommended Agent Workflow

1. analyze_project — check project health
2. workflow_setup_landing_page with mode:"plan" — get component recommendations
3. Review selectedComponents and missingSections
4. workflow_setup_landing_page with mode:"apply" — install all components
5. Use pageTemplate from the response — paste directly into app/page.tsx
6. npm run build — validate

AI Agent Prompts

Copy these prompts directly into your AI agent (Cursor, Windsurf, Claude Code) after running beste init.

Author / Creator Landing Page

You are building a personal landing page for an author using beste-cli MCP tools.

Page sections needed:
- Hero (author photo, name, tagline, social links)
- Books showcase with chronological timeline (oldest → newest, cover images, descriptions, buy links)
- Speaking / conferences (upcoming and past events, topics)
- Interviews & press (video or article cards with thumbnails)
- About / biography (short text, awards, credentials)
- Newsletter / CTA (email signup or contact)
- Footer

Steps:
1. Call analyze_project to verify project health.
2. Call workflow_setup_landing_page with niche="author personal brand", style="editorial minimal elegant", audience="readers book lovers publishers", mode="plan".
3. Review selectedSections and missingSections in the response.
4. Call workflow_setup_landing_page again with mode="apply" to install components.
5. Use search_codebase to find app/page.tsx.
6. Copy the pageTemplate from the response into app/page.tsx — it already has correct imports from component-data.ts.
7. Replace demo data props with real author content placeholders (name, book titles, event dates, interview URLs).
8. For the books timeline, render items in chronological order (use a sorted array by year).
9. Run npm run build and fix any errors.

Import rule: Always import demo data from @/lib/beste/component-data, never from the component file directly.

Multi-Page SaaS Product Website

You are building a multi-page SaaS product website using beste-cli MCP tools.

Product: A project management tool for remote teams.

Pages to create:
- app/page.tsx — Marketing home (hero, feature highlights, social proof, pricing teaser, CTA)
- app/features/page.tsx — Full features breakdown (icon grid, comparison table, stats)
- app/pricing/page.tsx — Pricing plans (cards, FAQ, money-back guarantee CTA)
- app/about/page.tsx — Company story, team grid, values, press logos

Steps:
1. Call analyze_project — check health and catalog status.
2. For each page, call workflow_setup_landing_page with mode:"plan" and the appropriate niche:
   - Home: niche="saas project management", style="modern bold", audience="startup teams remote workers"
   - Features: niche="saas features", style="technical clean", audience="product managers developers"
   - Pricing: niche="saas pricing", style="conversion focused", audience="decision makers"
   - About: niche="company about team", style="human warm", audience="investors job seekers"
3. Present all 4 plans together — wait for approval before installing.
4. Run workflow_setup_landing_page with mode:"apply" for each page in order.
5. Use search_codebase to find or confirm the app directory structure.
6. Create each page file using the pageTemplate from its apply response.
   - Import demo data from @/lib/beste/component-data — never from component files directly.
7. Create app/layout.tsx if missing — include a shared navbar component across all pages.
8. Use search_codebase with query="NavBar OR Navbar OR nav" to find an installed navbar and wire it into the layout.
9. Run npm run build — fix any import or type errors before finishing.

Constraints:
- Each page must be a separate page.tsx in its own folder.
- Navbar should appear on every page via layout, not repeated per page.
- Do not duplicate components across pages — reuse where it makes sense.
- Import rule: demo data always from @/lib/beste/component-data.

Authentication (Pro Accounts Only)

Authentication is optional and only required for pro/premium components. Free components work without logging in.

Option 1: Local Login (Recommended for Human Users)

If you have a beste.co Pro account, log in once to access premium components:

beste login

You will be prompted for your email and license key. Credentials are saved locally at ~/.beste/config.json and automatically attached to every request.

Once logged in, you can install premium components just like free ones:

beste add navbar39

To remove your saved credentials:

beste logout

Check whether credentials exist and license validation passes:

beste --json auth status

Option 2: Per-Request Authentication (Recommended for AI Agents)

For AI agents and automated workflows, you can provide credentials directly with each command using --email and --license-key flags:

# CLI usage
beste add feature81 --email "[email protected]" --license-key "YOUR-LICENSE-KEY"

# MCP tool usage
beste --json mcp call install_component --args '{"component":"feature81","email":"[email protected]","licenseKey":"YOUR-LICENSE-KEY"}'

# MCP batch usage
beste --json mcp call components_ensure --args '{"names":["feature81","feature82"],"email":"[email protected]","licenseKey":"YOUR-LICENSE-KEY"}'

Important syntax note:

• beste add does not support --args
• Wrong: beste add faq17 --args '{"email":"...","licenseKey":"..."}'
• Correct (CLI): beste add faq17 --email "..." --license-key "..."
• Correct (MCP): beste --json mcp call components_ensure --args '{"names":["faq17"],"email":"...","licenseKey":"..."}'

Why per-request auth?

• AI agents typically don't have access to beste login session state
• Works reliably in automated and CI/CD environments
• No need to manage stored credentials
• Each request is self-contained

Supported in:

• beste add command (--email and --license-key flags)
• install_component MCP tool (email and licenseKey parameters)
• install_components_batch MCP tool
• components_ensure MCP tool
• workflow_setup_landing_page MCP tool

Supported Package Managers

The CLI automatically detects and uses your preferred package manager:

• npm
• pnpm
• yarn
• bun

🛠️ How It Works

1. Directory Detection: Checks components.json and respects your path aliases
2. Component Fetching: Downloads component data from beste.co
3. File Installation: Places files in the correct directory structure
4. Demo Data Extraction: Saves *Demo exports to lib/beste/component-data.ts
5. Dependency Check: Compares required packages with your package.json
6. Installation: Offers to install missing dependencies with your package manager

📋 Requirements

• Node.js 18 or higher
• A React/Next.js project with shadcn/ui setup (recommended)

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

📄 License

MIT © compbyter

🔗 Links

• Official Website
• GitHub Repository
• npm Package
• Report Issues

Made with ❤️ for the beste.co community