@duffcloudservices/cli

Command-line interface for initializing and managing DCS (Duff Cloud Services) customer sites.

Installation

npm install -g @duffcloudservices/cli
# or
pnpm add -g @duffcloudservices/cli

Quick Start

# 1. Authenticate with Google OAuth
dcs login

# 2. Initialize a new customer site
cd /path/to/customer-site
dcs init --site-slug my-site --site-name "My Site"

# 3. Validate configuration
dcs validate

# 4. Generate integration plans
dcs plans

Commands

Authentication

# Login with Google OAuth (device flow)
dcs login

# Check current user
dcs whoami

# Logout and clear credentials
dcs logout

Site Management

# List sites you have access to
dcs sites list

# Show details for a specific site
dcs sites show my-site

Initialization

# Initialize DCS integration in current directory
dcs init --site-slug my-site --site-name "My Site"

# Specify target directory
dcs init -s my-site -n "My Site" -t ./my-site

# Specify framework (vue or astro)
dcs init -s my-site -n "My Site" -f astro

# Preview without creating files
dcs init -s my-site -n "My Site" --dry-run

# Overwrite existing files
dcs init -s my-site -n "My Site" --force

Validation

# Validate .dcs configuration files
dcs validate

# Validate a specific directory
dcs validate -t ./my-site

# Show verbose output
dcs validate -v

Integration Plans

# Generate AI-assisted integration plans
dcs plans

# Regenerate existing plans
dcs plans --force

Page Snapshot Capture

# Capture all pages listed in .dcs/pages.yaml
dcs capture-snapshots --target ./customer-site --base-url http://localhost:5173

# Capture only selected page slugs
dcs capture-snapshots --target ./customer-site --base-url http://localhost:5173 --pages home,about

Snapshot output uses a fixed portal contract:

| File | Portal use | Capture behavior | | --- | --- | --- | | site-snapshots/{pageSlug}/full-page.png | Expanded page dialog with auto-scroll | Full scrollable page after a lazy-load pass | | site-snapshots/{pageSlug}/thumbnail.png | Pages grid cards | Header/hero-focused 16:9 top crop captured at the site desktop viewport | | site-snapshots/{pageSlug}/sections/{sectionId}.png | Visual-editor section overlays | Individual data-section element screenshots |

Full-page captures must reset scroll after the lazy-load pass and temporarily pin fixed/sticky site navigation to the document origin during page.screenshot({ fullPage: true }). Without that capture-time layout guard, Playwright can render a fixed top nav near the footer because the page was scrolled before the full-page image was assembled.

Keep these names stable across customer-site scripts. Site-specific flexibility belongs in .dcs/pages.yaml (snapshot.viewport, waitAfterLoad, page paths) and in environment variables such as SITE_PREVIEW_URL, not in alternate artifact names.

For managed CSS-style backgrounds or any customer-editable hero/card/staff/gallery image, render a real image layer with ManagedImage from @duffcloudservices/cms/managed-image (or the same local pattern for framework-specific sites), backed by matching .dcs/content.yaml URL and alt keys. The actual <img> must expose data-dcs-image-key, data-dcs-image-url, and data-dcs-image-alt; snapshot capture records those markers as editable image keys, which keeps images visible in full-page screenshots and replaceable from the visual editor.

Generated Files

The init command creates the following structure:

.dcs/
├── site.yaml          # Site identity and Azure config
├── pages.yaml         # Page registry for CMS
├── content.yaml       # Text content (managed by Portal)
├── seo.yaml           # SEO configuration (managed by Portal)
└── SECTION-CONVENTIONS.md

.github/
└── copilot-instructions.md

.plans/
├── README.md
├── 00-audit-site.md
├── 01-create-use-text-content.md
├── 02-integrate-home-page.md
├── 03-integrate-remaining-pages.md
├── 04-capture-snapshots.md
└── 05-verify-deployment.md

Authentication Flow

The CLI uses OAuth 2.0 Device Authorization Grant (RFC 8628):

1. Run dcs login
2. CLI displays a URL and code
3. Open URL in browser, enter code
4. Sign in with Google
5. CLI receives and stores tokens securely

Tokens are stored encrypted in your OS keychain/credential store.

Site Access Validation

Before creating configuration files, the CLI validates:

1. You're authenticated
2. You have access to the specified site (or can create it)
3. You have editor/admin permissions

This prevents creating configs for sites you don't have access to.

Next Steps After Init

1. Install CMS package: pnpm add @duffcloudservices/cms
2. Configure Vite plugins in your build config
3. Follow the plans in .plans/ directory
4. Register site in DCS Portal

Requirements

• Node.js >= 18.0.0
• DCS Portal account with Google OAuth

License

MIT © Duff Cloud Services