@duffcloudservices/cli

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

📦 Package Info

npm: @duffcloudservices/cli

Installation

# Global installation (recommended)
npm install -g @duffcloudservices/cli

# Or with pnpm
pnpm add -g @duffcloudservices/cli

# Or run directly with npx
npx @duffcloudservices/cli init

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

dcs login

Authenticate with DCS Portal using Google OAuth (device flow).

dcs login

The CLI will display a URL and code. Open the URL in your browser, enter the code, and sign in with Google. Tokens are saved to a local configuration file in your user config directory (managed by the conf package under the dcs-cli project name). Run dcs logout to clear them, and avoid running dcs login on shared or untrusted machines.

dcs logout

Clear stored credentials.

dcs logout

dcs whoami

Display the current authenticated user.

dcs whoami
# Output: Logged in as: user@example.com

---

Site Management

dcs sites list

List all sites you have access to manage.

dcs sites list

dcs sites show <slug>

Show details for a specific site.

dcs sites show my-site

---

Site Initialization

dcs init

Initialize DCS integration in a customer site repository.

dcs init --site-slug <slug> --site-name "<name>" [options]

Options:

Option	Alias	Description
--site-slug <slug>	-s	URL-safe site identifier (required)
--site-name <name>	-n	Human-readable site name (required)
--target <dir>	-t	Target directory (default: current)
--framework <type>	-f	Framework: vue or astro (default: vue)
--dry-run		Preview without creating files
--force		Overwrite existing files

Examples:

# Initialize in current directory
dcs init -s kinetic-energy -n "Kinetic Energy Solutions"

# Initialize in a specific directory
dcs init -s my-site -n "My Site" -t ./my-site

# Specify Astro framework
dcs init -s my-site -n "My Site" -f astro

# Preview what would be created
dcs init -s my-site -n "My Site" --dry-run

---

Validation

dcs validate

Validate .dcs configuration files.

dcs validate [options]

Options:

Option	Alias	Description
--target <dir>	-t	Directory to validate (default: current)
--fix		Attempt to fix common issues
--verbose	-v	Show detailed output

The validator checks:

• Required configuration files exist
• YAML syntax is valid
• Required fields are present
• Site slug format is correct
• Pages configuration is valid

---

Integration Plans

dcs plans

Generate AI-assisted integration plans for implementing DCS features.

dcs plans [options]

Options:

Option	Description
--force	Regenerate existing plans

This creates markdown files in .plans/ that guide you through integrating DCS features step by step.

---

Snapshots

dcs capture-snapshots

Capture visual snapshots of your site's pages for the portal page editor. Run it against a locally running build of your site.

dcs capture-snapshots [options]

Options:

Option	Alias	Description
--target <dir>	-t	Directory containing .dcs/pages.yaml (default: current)
--base-url <url>	-u	Base URL of the running site (default: http://localhost:5173)
--pages <slugs>	-p	Comma-separated list of page slugs to capture
--dry-run		Show what would be captured without launching a browser
--verbose	-v	Show detailed output

The snapshots drive the portal's visual page editor, giving each managed page a current visual reference.

---

Generated Files

Running dcs init 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 # Documentation for content sections

.github/
└── copilot-instructions.md  # AI assistant context

.plans/
├── README.md
├── 00-audit-site.md           # Initial audit checklist
├── 01-create-use-text-content.md  # Composable setup
├── 02-integrate-home-page.md  # Home page integration
├── 03-integrate-remaining-pages.md  # Other pages
├── 04-capture-snapshots.md    # Portal snapshot setup
└── 05-verify-deployment.md    # Final verification

Configuration Files

.dcs/site.yaml

Site identity and Azure configuration:

site:
  slug: my-site
  name: My Site
  framework: vue

azure:
  staticWebApp:
    name: swa-my-site
    resourceGroup: rg-dcs-sites

.dcs/pages.yaml

Page registry for the CMS:

pages:
  - slug: home
    path: /
    type: static
    title: Home
    deletable: false
    textKeys: []

  - slug: about
    path: /about
    type: static
    title: About
    deletable: true
    textKeys: []

.dcs/content.yaml

Text content (managed via Portal):

version: 1
lastUpdated: null
updatedBy: null

global: {}

pages:
  home: {}
  about: {}

---

Authentication Flow

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

┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   CLI       │────▶│  DCS Portal API  │────▶│  Google OAuth   │
│  (Node.js)  │◀────│  /api/v1/auth/*  │◀────│  Consent Screen │
└─────────────┘     └──────────────────┘     └─────────────────┘
       │
       ▼
┌─────────────────────┐
│  Local config file   │  (dcs-cli config in your user config directory)
└─────────────────────┘

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 the tokens and writes them to its local config file

---

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.

---

Workflow: New Site Integration

Complete workflow for integrating a new customer site:

1. Install CLI

npm install -g @duffcloudservices/cli

2. Authenticate

dcs login

3. Initialize Site

cd /path/to/customer-site
dcs init -s customer-name -n "Customer Name LLC"

4. Install CMS Package

pnpm add @duffcloudservices/cms

5. Configure Vite

// vite.config.ts or .vitepress/config.ts
import { dcsContentPlugin, dcsSeoPlugin } from '@duffcloudservices/cms/plugins'

export default defineConfig({
  plugins: [
    dcsContentPlugin(),
    dcsSeoPlugin()
  ]
})

6. Follow Integration Plans

Work through the files in .plans/ directory:

# Check progress
ls .plans/

# Open in VS Code
code .plans/

7. Validate Configuration

dcs validate

8. Register in Portal

The site will be available for management in the DCS Portal once the first deployment completes.

---

Offline Mode

The CLI works offline for these commands:

• dcs init — Creates configuration files locally
• dcs validate — Validates local configuration
• dcs plans — Generates integration plans

Authentication is required for:

• dcs sites — Requires API access
• Live validation features (future)

---

Troubleshooting

"Command not found: dcs"

Ensure the package is installed globally:

npm install -g @duffcloudservices/cli
# Or use npx
npx @duffcloudservices/cli --help

Authentication fails

1. Check your internet connection
2. Ensure you have a valid Google account
3. Try dcs logout then dcs login again

Validation errors

Run with verbose output for details:

dcs validate -v

Site slug already exists

If you're re-initializing a site, use --force:

dcs init -s my-site -n "My Site" --force

---

Requirements

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

---

Related

• @duffcloudservices/cms Documentation
• Partner Onboarding Guide
• site.yaml Reference