SmartSite CLI

Advanced admin layer synchronization and update tool for Smart Site projects

The SmartSite CLI is a powerful command-line tool designed to manage Smart Site installations, with a primary focus on keeping admin layers synchronized across different environments - from local development to production deployments.

Installation

The CLI is integrated into the monorepo and available via pnpm:

# From monorepo root
pnpm smartsite [command] [options]

# Or use directly
node packages/cli/dist/index.js [command] [options]

Bootstrap & Setup

The init command runs the Smart Site starter wizard directly inside the CLI so you can configure .env, secrets, storage, and admin credentials without any legacy scripts.

# Run inside the monorepo (defaults to apps/smart-site)
pnpm smartsite init

# Run anywhere (downloads the starter if it's missing)
pnpm dlx smartsite@latest init

# Target a specific directory and skip prompts (use defaults + --no-seed)
pnpm smartsite init \
  --project apps/clients/acme \
  --site-name "Acme Robotics" \
  --db-url "mongodb+srv://..." \
  --admin-email [email protected] \
  --admin-password "Sup3rSecure!" \
  --no-seed \
  --yes

Key flags:

• --port <number> – override the dev server port that will be stored in NEXT_PUBLIC_URL
• --db-provider <mongoose|postgres> / --db-url <uri> – pick the database + connection string
• --storage <local|vercel-blob> / --blob-token – toggle between local files and Vercel Blob
• --no-seed / --no-blog – skip the automatic seed or drop the optional blog content
• --no-browser – prevent the wizard from opening the site after seeding
• -p, --project <path> – point at a specific folder; if omitted, the CLI uses the current directory when it's empty or creates ./smart-site.

The command copies .env.example, patches the selected values in-place (preserving inline comments), ensures Payload secrets exist, updates package.json scripts with the chosen port, toggles the storage provider inside smartsite.config.ts, and—when seeding is enabled—boots next dev, calls /api/seed, and leaves the dev server running.

When the starter isn’t already present, the CLI now downloads the latest Smart Site archive from GitHub (using your authenticated access), copies the starter files into the target directory, runs pnpm install automatically, and then launches the setup wizard. No monorepo checkout or manual install step is required.

Database Seeding

Use the dedicated seed command to re-run /api/seed later or seed remote environments. It can reuse an existing dev server, start one automatically, or point to any reachable Smart Site URL:

# Hit the local dev server currently running on port 3000
pnpm smartsite seed starter

# Start a fresh dev server on port 4000, skip blog content, and keep the browser closed
pnpm smartsite seed starter --start-dev --port 4000 --no-blog --no-browser

# Seed a deployed staging site via HTTPS
pnpm smartsite seed starter --url https://staging.acme-smart-site.com --site-name "Acme Staging"

Flags:

• --url <base> – seed against any environment (defaults to NEXT_PUBLIC_URL or http://localhost:3000)
• --start-dev / --port <number> – boot a temporary dev server before seeding
• --site-name <name> – override the value sent to the Smart Site AI seed manager
• --no-blog – skip optional blog/insights content
• --no-browser – skip the automatic browser launch when --start-dev is used

Smart Site AI Management

Use the ai command group to manage workspace access end-to-end:

# Rotate/ensure the hidden ai-agent user + API key
pnpm smartsite ai rotate [--force] [--site-name "Acme Robotics"]

# Check current enablement/pending/suspended status
pnpm smartsite ai status

# Submit or retry the approval request (no admin UI required)
pnpm smartsite ai apply

These commands read .env, bootstrap Payload inside your project, and update the local environment automatically—no more scripts/register-ai.ts or ad-hoc curl commands.

Staging Sync

Mirror MongoDB data between production and staging directly from the CLI (no external scripts required):

# Pull production data into staging (backs up staging first)
pnpm smartsite staging pull

# Push staging into production, skip backup, and bypass the confirmation prompt
pnpm smartsite staging push --skip-backup --yes

Common flags:

• -p, --project <path> – point at an alternate Smart Site project.
• --skip-backup – skips the automatic mongodump before syncing (not recommended).
• --retention <count> – adjust how many backups to retain in apps/.../backups (defaults to 5).
• --prod-uri / --staging-uri – temporarily override DATABASE_URL or STAGING_DATABASE_URL without editing .env.
• -y, --yes – skip the destructive-action confirmation when pushing to production.

Fresh Client Installs

Spin up a new client workspace based on the canonical starter with init:

# Copy apps/smart-site to apps/clients/acme
pnpm smartsite init acme

# Choose a custom destination
pnpm smartsite init atlas --directory apps/clients/atlas-enterprise

The command copies the starter (excluding build artifacts), rewrites package.json with the new package name, and leaves a ready-to-run project that can immediately be configured via pnpm smartsite init --project apps/clients/<name>.

Core Concept: Admin Layer Updates

The Smart Site system separates the admin layer (core CMS functionality) from frontend customizations. This allows you to:

• Update core functionality without losing customizations
• Sync improvements across multiple projects
• Maintain version control for the admin system
• Pull updates from the official Smart Site repository

The admin layer includes:

• /src/admin/ - Complete admin directory
• Payload CMS configuration
• Core utilities and components
• System-level dependencies

Update Command (Primary Feature)

The update command is the heart of the CLI, providing multiple ways to synchronize admin layers.

Basic Update (from GitHub)

Update a single site from the latest GitHub release:

# Update current directory
pnpm smartsite update

# Update specific client
pnpm smartsite update --target elvora
pnpm smartsite update --target apps/clients/elvora

# Update with specific version
pnpm smartsite update --version v2.1.0

# Use edge version (latest master)
pnpm smartsite update --edge

Bulk Updates

Update all client sites simultaneously:

# Update all clients to latest
pnpm smartsite update --all

# Update all to specific version
pnpm smartsite update --all --version v2.1.0

# Dry run to see what would change
pnpm smartsite update --all --dry-run

Manual Transfer Mode (Local Updates)

The most powerful feature - sync between local projects without GitHub:

# After manually copying admin folder
cp -r source/src/admin target/src/admin
pnpm smartsite update --target target --manual-transfer

# This handles dependency sync, compatibility checks, etc.

Monorepo Mirror Command

Use the SmartSite CLI to mirror the canonical starter into the demo without extra scripts:

# Mirror starter → demo (dry run + apply)
pnpm smartsite sync-demo --dry-run
pnpm smartsite sync-demo

# Legacy alias (prints deprecation notice)
pnpm smartsite sync-starter

sync-demo will:

1. Export starter code from the working tree or a provided git ref
2. Copy shared admin and utility files into apps/smart-site
3. Preserve demo-only frontend surfaces and seed endpoints
4. Prune demo copies of starter-owned files that were removed upstream

Blocks Library Registry Commands

The CLI can browse and install blueprint sections from the Smart Site Blocks Library. By default it targets the hosted registry; override with SMARTSITE_REGISTRY_ORIGIN or the --registry flag to test against a local build.

Authentication Requirements

Access to the registry requires membership in the private andy-dextrous/product-studio repository. Authenticate once with GitHub and the CLI will persist the device-flow token securely:

# Authenticate (opens GitHub device code flow)
pnpm smartsite login

# Confirm status or troubleshoot
pnpm smartsite whoami

Registry endpoints reject unauthenticated requests. The CLI forwards your bearer token automatically, so manual curl calls will fail unless the same header is provided.

List available sections

# Human-readable catalogue
pnpm smartsite sections list

# JSON manifest (useful for tooling)
pnpm smartsite sections list --json

# Point at custom registry origin
pnpm smartsite sections list --registry http://localhost:4310

Install a section blueprint

# Install to the starter's sections directory (auto-registers when possible)
pnpm smartsite sections add content/test-section

# Choose a different destination and skip dependency installs
pnpm smartsite sections add hero/hero-home \
  --dest apps/clients/acme/src/components/sections \
  --no-install \
  --yes

# Preview the files and automation without touching disk
pnpm smartsite sections add hero/hero-home --dry-run

# Opt out of automatic wiring (manual follow-up required)
pnpm smartsite sections add hero/hero-home --no-automate

Install command writes three files—Component.tsx, config.ts, and meta.json (including snapshot URLs and registry origin). When the destination is the starter, the CLI also updates sections/config.ts, sections-map.tsx, and any required dependencies unless you pass --no-automate.

List field presets

# Human-readable catalogue
pnpm smartsite fields list

# JSON manifest (useful for tooling)
pnpm smartsite fields list --json

# Point at custom registry origin
pnpm smartsite fields list --registry http://localhost:4310

Install a field preset

# Install to the starter's fields directory
pnpm smartsite fields add section-intro

# Choose a different destination and auto-overwrite
pnpm smartsite fields add pagination \
  --dest apps/clients/acme/src/components/fields \
  --overwrite \
  --yes

Field installs copy the combined Payload helper + React renderer into your target directory so collections and sections can reuse the starter-aligned presets.

List GSAP animations

# Human-readable catalogue
pnpm smartsite animations list

# JSON manifest (useful for tooling)
pnpm smartsite animations list --json

# Point at custom registry origin
pnpm smartsite animations list --registry http://localhost:4310

Install a GSAP animation

# Add an animation effect to the starter (auto-import + plugin toggle)
pnpm smartsite animations add fade-in-up

# Install into a client project and skip dependency installation
pnpm smartsite animations add hero-headline-reveal \
  --dest apps/clients/acme/src/providers/gsap/effects \
  --no-install \
  --yes

# Preview automation without applying changes
pnpm smartsite animations add fade-in-up --dry-run

Animation installs include the effect file, optional demo component, and meta.json manifest. When installed into the starter, the CLI automatically imports the effect in providers/gsap/effects.ts and enables required plugins inside smartsite.config.ts. Dependencies are resolved the same way as sections—accept the prompt to install missing packages or supply --no-install to handle them manually.

Run interactive setup

# Configure environment variables for the starter (prompts for DB, storage, seed)
pnpm smartsite init

# Configure the Blocks Library (same flow)
pnpm smartsite setup blocks --project apps/blocks-library

These commands wrap the existing scripts/setup.ts flows, so you can use the CLI instead of remembering pnpm incantations. Pass --project to point at a different workspace root.

Seed demo content

# Seed the starter (ensure the dev server is running on port 3000)
pnpm smartsite seed starter

# Seed the Blocks Library catalogue
pnpm smartsite seed blocks --project apps/blocks-library

The commands proxy the existing pnpm run seed scripts. If the HTTP request fails, check that the respective app is running locally.

Doctor (health check)

# Inspect the starter for missing component registrations or GSAP wiring
pnpm smartsite doctor

# Target a specific project directory
pnpm smartsite doctor --project apps/clients/acme

The doctor command scans installed section and animation metadata, confirms component/config files exist, verifies sections/config.ts, sections-map.tsx, providers/gsap/effects.ts, and smartsite.config.ts were updated correctly, and flags anything that needs manual attention.

Update Options

| Option | Description | Example | |--------|-------------|---------| | --target | Specify target directory or client name | --target elvora | | --version | Update to specific version | --version v2.1.0 | | --edge | Use latest master branch | --edge | | --all | Update all clients | --all | | --force | Skip compatibility checks | --force | | --dry-run | Preview changes without applying | --dry-run | | --no-install | Skip dependency installation | --no-install | | --manual-transfer | Use pre-copied files (skip download) | --manual-transfer |

Common Workflows

Development Cycle

# 1. Develop features in smart-site (canonical)
# ... make changes ...

# 2. Mirror starter into the demo for showcase validation
pnpm smartsite sync-demo

# 3. Extend the demo with optional animations/sections
# ... refine code ...

# 4. Commit and push to trigger external publish
git commit -am "feat: promote starter updates"
git push

Client Site Maintenance

# Update single client from GitHub
pnpm smartsite update --target client-name

# Update all clients
pnpm smartsite update --all

# Test update first
pnpm smartsite update --target client-name --dry-run

Version Management

# Check current version
cat apps/client-name/src/admin/version.json

# Update to specific version
pnpm smartsite update --target client-name --version v2.0.0

# Rollback (by specifying older version)
pnpm smartsite update --target client-name --version v1.9.0

Local Development Testing

# Test admin changes without GitHub
cp -r apps/smart-site/src/admin apps/smart-site-demo/src/admin
pnpm smartsite update --target smart-site --manual-transfer

# Or mirror via CLI
pnpm smartsite sync-demo --dry-run
pnpm smartsite sync-demo

How Updates Work

1. Source Detection: Determines source (GitHub release, edge, or local)
2. Compatibility Check: Validates framework versions
3. Backup Creation: Preserves current state (in git)
4. Admin Replacement: Removes old, copies new admin folder
5. Dependency Sync: Updates package.json with admin requirements
6. Post-Update: Runs install, type generation, etc.

Compatibility & Safety

The CLI includes several safety features:

• Version tracking via admin/version.json
• Framework compatibility checks before updating
• Dependency synchronization to prevent mismatches
• Git integration for rollback capability
• Dry run mode to preview changes

Authentication

For GitHub updates, you'll need authentication:

# Login to GitHub (one-time setup)
pnpm smartsite login

# Check auth status
pnpm smartsite whoami

# Logout
pnpm smartsite logout

Sync Demo Command (Monorepo Only)

For internal development use only – mirrors the canonical starter into the showcase demo:

# Mirror the starter into the demo environment
pnpm smartsite sync-demo

# Dry run against a tagged starter release
pnpm smartsite sync-demo --ref v2.3.0 --dry-run

This command:

• Copies starter-admin and shared code from apps/smart-site into apps/smart-site
• Skips demo-only marketing surfaces (frontend routes, sections, animations, etc.)
• Prunes demo copies of starter-owned files that were removed upstream
• Keeps the starter as the canonical artifact while ensuring the demo stays up-to-date

The legacy sync-starter command is now an alias that prints a deprecation warning and delegates to sync-demo.

Sync Client Command (Monorepo Only)

For internal development use - mirrors the latest Smart Site build into a client directory while keeping brand surfaces intact:

# Sync starter (or custom source) into a client named elvora
pnpm smartsite sync-client elvora

# Dry run with additional preserved paths and alternate source
pnpm smartsite sync-client elvora --dry-run --source apps/smart-site --preserve "public/custom-assets" "src/components/custom"

Key behavior:

• Sources from apps/smart-site by default (override with --source)
• Preserves brand-critical areas like sections, CSS, public assets, GSAP setup, extensions, and config
• Merges package.json, retaining client-specific dependencies, scripts, and workspace metadata
• Supports --dry-run previews plus interactive client selection when none is provided

Run this after updating the starter to pull the newest Smart Site features into active client implementations without overwriting bespoke frontend work.

Other Commands (Brief Mention)

Create New Site

# Create from smart-site template
pnpm smartsite create client-name

# With configuration prompts
pnpm smartsite init client-name

Validation

# Validate Smart Site installation
pnpm smartsite validate

# Check for issues
pnpm smartsite doctor

Troubleshooting

Update Fails with "Not a valid SmartSite installation"

Ensure the target has:

• /src/admin/ directory structure
• /src/app/ or next.config.ts
• Required admin subdirectories

Dependency Conflicts

# Force update (skip compatibility)
pnpm smartsite update --force

# Or update frameworks first
pnpm install next@latest payload@latest
pnpm smartsite update

Manual Transfer Not Working

Ensure you've copied the entire admin folder:

# Correct: entire admin directory
cp -r source/src/admin target/src/admin

# Wrong: just contents
cp -r source/src/admin/* target/src/admin/

Architecture Notes

The CLI is designed for the Smart Site three-tier architecture:

1. smart-site (master) - Development with full features
2. smart-site - Clean template for distribution
3. Client sites - Production deployments

Updates can flow:

• Downstream: master → starter → clients → external
• Upstream: external → clients → starter → master
• Lateral: between any two sites via manual transfer

Future Enhancements

Planned features (not yet implemented):

• Selective section sync
• Automated compatibility resolution
• Rollback command
• Diff visualization
• Migration scripts for breaking changes

For more information about Smart Site architecture, see the main README.