ppcos-cli

CLI tool to distribute and manage Claude Code skills and agents for Google Ads workflows.

Installation

npm install -g ppcos

Requires Node.js 18+.

Quick Start

# Create a hub folder and navigate to it
mkdir ppcos-hub && cd ppcos-hub

# Create main-config.json template
ppcos init

# Edit main-config.json with your client names, then:
ppcos init-all

# Check status of all clients
ppcos status

# Update all clients when new version is released
ppcos update

Commands

ppcos init [client-name]

Without args: create main-config.json template. With client name: create a client workspace.

ppcos init                            # Create main-config.json template
ppcos init client-acme                # Create client workspace
ppcos init client-acme --skip-config  # Don't add to main-config.json

Creates:

clients/client-acme/
├── .managed.json          # Tracks managed files
├── .claude/
│   ├── skills/            # 6 Google Ads skills
│   ├── agents/            # 4 specialized agents
│   └── settings.local.json
├── CLAUDE.md              # Client context template
├── config/                # API credentials
├── context/               # Client data
└── created/               # Generated assets

ppcos init-all

Initialize all clients defined in main-config.json.

ppcos init-all
ppcos init-all --force  # Reinitialize existing clients (backs up first)

main-config.json example:

{
  "version": "1.0",
  "clients": [
    { "name": "client-acme", "enabled": true },
    { "name": "client-beta", "enabled": true },
    { "name": "client-gamma", "enabled": false }
  ]
}

ppcos update

Update base skills in all clients while preserving custom work.

ppcos update                    # Update all clients
ppcos update --client acme      # Update specific client
ppcos update --dry-run          # Show what would change

Conflict handling:

• Unchanged files: automatically updated
• Modified files: prompts with options (backup/skip/cancel)
• Custom files: never touched

Updating client-acme (v1.0.0 → v1.1.0)

⚠ Modified files detected:
  - .claude/skills/rsa-maker/SKILL.md

Options:
  [1] Backup and overwrite (files saved to .backup/)
  [2] Skip modified files (keep your changes)
  [3] Cancel update

Choice [1/2/3]:

ppcos status

Show version and modification status for all clients.

ppcos status
ppcos status --client acme  # Show specific client only

Output:

ppcos-hub/

  client-acme
    Version: 1.0.0 → 1.1.0 available
    Managed: 42 files
    Modified: 2 files
      - .claude/skills/rsa-maker/SKILL.md
    Custom: 1 skill
    Conflicts: 0

  client-beta
    Version: 1.1.0 (up to date)
    Managed: 42 files
    Modified: 0 files
    Custom: 0 skills
    Conflicts: 0

Package version: 1.1.0

Included Skills

| Skill | Description | |-------|-------------| | gads-context | Pull Google Ads account data (campaigns, ads, keywords) | | competitor-scraper | Fetch competitor ads via DataForSEO API | | ads-context-gatherer | Gather brand context from websites | | offer-angles | Extract offer message angles for RSA composition | | rsa-maker | Create Responsive Search Ads from offer angles | | search-term-analyzer | Analyze search terms for keyword opportunities | | account-changelog | Fetch account change history from Google Ads | | landing-page-builder | Generate high-converting landing page wireframes | | ecom-page-builder | Generate ecommerce page wireframes with product-first layouts |

Included Agents

| Agent | Description | |-------|-------------| | qs-decider | Quality Score improvement coordinator | | ad-relevance-analyzer | Analyze ad relevance issues | | expected-ctr-analyzer | Analyze expected CTR issues | | landing-page-analyzer | Analyze landing page experience |

How It Works

Managed vs Custom Files

• Managed files: Created by init, tracked in .managed.json, updated by CLI
• Custom files: Created by you, never touched by updates

Add your own skills to .claude/skills/ - they'll never be modified.

Update Safety

1. Calculates SHA256 checksum of each managed file
2. Compares with stored checksum in .managed.json
3. Unchanged files: updated silently
4. Modified files: user prompted (backup/skip/cancel)
5. Custom files: completely ignored

Typical Workflow

# Setup (once)
mkdir ppcos-hub && cd ppcos-hub
ppcos init client-acme
cd clients/client-acme

# Daily work
# Edit CLAUDE.md with client context
# Run /ppcos to gather brand info
# Create ads with /rsa-maker

# When CLI updates
cd ../..
ppcos update

Configuration

config/.env.example

Template for API credentials. Copy to .env and fill in:

GOOGLE_ADS_DEVELOPER_TOKEN=your_token
GOOGLE_ADS_CLIENT_ID=your_client_id
GOOGLE_ADS_CLIENT_SECRET=your_client_secret
GOOGLE_ADS_REFRESH_TOKEN=your_refresh_token
DATAFORSEO_USERNAME=your_username
DATAFORSEO_PASSWORD=your_password

config/ads-context.config.json

Per-client settings:

{
  "customerId": "1234567890",
  "competitors": ["competitor1.com", "competitor2.com"],
  "targetLocations": ["United States"]
}

Adding Skills to the Base

To add a new skill that gets distributed to all clients:

1. Create the skill folder in .claude-base/.claude/skills/<skill-name>/ with at minimum a SKILL.md
2. Bump the package version:

   npm version patch  # 1.0.0 → 1.0.1

3. Push to GitHub

Existing clients will receive the new skill on their next ppcos update. New clients get it automatically via ppcos init.

The same applies to agents (.claude-base/.claude/agents/) and any other base template files.

Why the version bump matters: The update command compares package.json version against each client's stored version. Without a bump, ppcos update sees clients as up-to-date and skips them.

License

Licensed for personal and internal business use only under the PPC Mastery General Terms & Conditions.

© 2026 PPC Mastery B.V. All rights reserved.