Hopkin CLI Skill#

When to Use#

Use this skill when the user:

• Asks about ad accounts, campaigns, ad sets, ads, or ad performance
• Wants to query Meta Ads, Google Ads, LinkedIn Ads, or Reddit Ads data
• Needs cross-platform advertising reports or comparisons
• References Hopkin, MCP ad servers, or ad platform APIs
• Asks to list, inspect, or analyze advertising entities

Do NOT use this skill for:

• General marketing questions unrelated to ad platform data
• Creating or modifying campaigns (Hopkin is read-only)
• Non-advertising analytics (website analytics, SEO, etc.)

Setup#

Installation#

Before using Hopkin, ensure it's installed and up to date:

bash

# Install globally from npm
npm install -g @hopkin/cli

# Or if already installed, check if an update is needed (do this if last check was >7 days ago)
npm outdated -g @hopkin/cli && npm install -g @hopkin/cli@latest

Authentication#

Check if the user is authenticated before making any data requests:

bash

hopkin auth status --json

If not authenticated, ask the user for their API key:

bash

hopkin auth set-key <API_KEY>

Users can get an API key from https://app.hopkin.ai/settings/api-keys

Discover Available Commands#

After authenticating, run hopkin --help to see all platforms, commands, and global flags. This also automatically refreshes the tool cache if it's stale (cache lasts 7 days).

bash

hopkin --help

Then drill down into a specific platform to see its resources and commands:

bash

hopkin meta --help
hopkin google --help
hopkin linkedin --help
hopkin reddit --help

And further into a resource to see its verbs and a specific command to see its flags:

bash

hopkin meta campaigns --help
hopkin meta campaigns list --help

Always use --help to discover what's available before guessing command names — platforms differ in their resource naming and available tools.

How to Use#

Query Data#

The CLI follows a consistent pattern:

text

hopkin <platform> <resource> [verb] [flags]

• platform: meta, google, linkedin, reddit
• resource: ad-accounts, campaigns, adsets, ads, etc.
• verb: list, get (defaults to list if omitted)
• flags: --reason (required for most commands), --account, --limit, etc.

Common Commands#

bash

# List ad accounts
hopkin meta ad-accounts list --reason "checking accounts" --json
hopkin google accounts list --reason "listing accounts" --json

# List campaigns for an account
hopkin meta campaigns list --account <ACCOUNT_ID> --reason "reviewing campaigns" --json

# Get performance insights
hopkin meta insights --account <ACCOUNT_ID> --reason "performance review" --json

# Ping a platform (health check)
hopkin meta ping --reason "connectivity test" --json

Format Output#

Always use --json when processing data programmatically. Other formats are available:

bash

# JSON (best for parsing)
hopkin meta ad-accounts list --reason "..." --json

# CSV (for spreadsheet export)
hopkin meta ad-accounts list --reason "..." --format csv

# TSV
hopkin meta ad-accounts list --reason "..." --format tsv

# Filter specific fields
hopkin meta ad-accounts list --reason "..." --json --fields id,name,currency

# Fetch all pages (for large result sets)
hopkin meta ad-accounts list --reason "..." --json --all

Important Notes#

• Read-only: Hopkin cannot modify campaigns, change budgets, or edit ads. It only reads data.
• --reason flag: Most commands require --reason "..." for audit trail purposes. Always include a brief, honest description of why you're querying the data.
• Account IDs: Many commands require --account <ID>. List accounts first to discover available IDs.
• Pagination: Results are paginated by default (25 per page). Use --all to fetch everything, or --limit N to control page size.
• Caching: The MCP servers cache data. Pass --refresh to a command if the user needs real-time data.
• Platform differences: Not all platforms have the same resources. Google has accounts (not ad-accounts), LinkedIn has campaign-groups and creatives (not adsets and ads). Always check hopkin <platform> --help first.

Update Check#

Before each session where you use Hopkin, check if the CLI needs updating. Do this if you haven't checked in the last 7 days:

bash

hopkin --version
npm view @hopkin/cli version

If the npm version is newer, update:

bash

npm install -g @hopkin/cli@latest

Troubleshooting#

bash

# Check auth status
hopkin auth status --json

# Debug a failing command
hopkin meta ad-accounts list --reason "debug" --json --debug

# Re-authenticate
hopkin auth set-key <NEW_KEY>

# Re-discover available commands (also refreshes tool cache)
hopkin --help