Cuppa CLI

Build and manage your entire brand from the command line. The Cuppa CLI gives AI agents and power users direct access to every Cuppa feature: content generation, SEO grading, bulk projects, social publishing, Brand DNA, Knowledge Bases, research agents, and more.

Who Is This For?

• AI agent developers building brand management workflows in Claude Code, Cursor, or any terminal-based AI
• Agencies managing multiple brands programmatically
• Power users who want to script content operations
• Developers integrating Cuppa into CI/CD or automation pipelines

Requirements

• Node.js 20+ (check with node --version)
• Cuppa account on Solo plan or higher
• Cuppa API key (created in Team Settings)

Installation

Option 1: Install globally (recommended)

npm install -g @cuppa-ai/cli

After installation, the cuppa command is available globally:

cuppa --version

Option 2: Run without installing

npx @cuppa-ai/cli --help

Option 3: Install from source

git clone https://github.com/cuppa-ai/cuppa-app.git
cd cuppa-app/packages/cli
npm install
npm run build
npm link

Setup

Step 1: Create an API Key

1. Go to Team Settings > API Keys
2. Click Create Key
3. Copy the key (you will not see it again)

Step 2: Authenticate the CLI

cuppa auth login

Paste your API key when prompted. The key is stored locally in ~/.cuppa/config.json.

Alternatively, set it as an environment variable:

export CUPPA_API_KEY="your-key-here"

Step 3: Initialize your default brand

cuppa init

This interactive command:

1. Verifies your API connection
2. Lists your available brands (sites)
3. Lets you select a default brand
4. Saves it so you do not need to pass --site-id on every command

Step 4: Verify everything works

cuppa status

You should see a summary of your brand: article counts, social posts, content planner items, and Brand DNA status.

Quick Start Workflows

Generate your first article

cuppa generate "best project management tools for remote teams"

This creates the article, polls until generation is complete, and auto-grades it for SEO. One command, full lifecycle.

Check performance

cuppa performance --period 30d

Pulls your Google Search Console data and shows keyword rankings, clicks, impressions, CTR, and average position.

Optimize an existing article

cuppa optimize <article-id>

Grades the article, researches SERP competitors, applies AI optimization, and re-grades to show the score change.

Publish to your CMS and social

cuppa publish <article-id> --platform ghost --social linkedin,twitter

Publishes the article to Ghost and generates social posts for LinkedIn and Twitter.

Run a full campaign

cuppa campaign create 
  --type mixed 
  --images 5 
  --videos 3 
  --articles 2 
  --social instagram,linkedin,youtube 
  --publish

Generates static image ads, video content, articles, and social copy for multiple platforms in a single command.

Command Reference

Workflow Commands (high-level)

Resource Commands (CRUD primitives)

Getting Help

Every command has built-in help:

cuppa --help
cuppa content --help
cuppa content create --help

Content Brief Parsing

Parse a content brief into structured article generation parameters (outline, keywords, tone, audience, instructions).

Parse from text

cuppa content parse-brief 
  --content "Target keyword: content marketing strategy. Write a 3000-word guide covering..." 
  --format json

Parse from a file

cuppa content parse-brief 
  --file ./my-brief.txt 
  --model claude-sonnet-4-5 
  --format json

The output includes the extracted outline, keywords, tone, audience, word count, content gaps, PAA questions, and extra instructions. Use these values with cuppa content create to generate an article based on the brief.

Social Media Commands

Generate for One Platform

cuppa social generate 
  --site-id <id> 
  --article-title "Spring Pet Grooming Tips" 
  --article-summary "A guide to spring grooming..." 
  --platform instagram 
  --generate-image 
  --tone engaging

Generate for Multiple Platforms

cuppa social multi 
  --site-id <id> 
  --article-title "Spring Pet Grooming Tips" 
  --article-summary "A guide to spring grooming..." 
  --platforms twitter,linkedin,instagram 
  --generate-images

Create + Schedule (Combined Workflow)

The recommended command for agents building a social calendar:

cuppa social create 
  --site-id <id> 
  --topic "Spring pet grooming tips" 
  --platforms twitter,linkedin,instagram 
  --include-images 
  --schedule-at "2026-04-15T10:00:00Z" 
  --tone professional

Generate a Week of Content

cuppa social generate-week 
  --site-id <id> 
  --platforms twitter,linkedin,instagram 
  --topics "topic1,topic2,topic3,topic4,topic5" 
  --start-date 2026-04-01 
  --include-images 
  --skip-weekends

Batch Schedule from File

cuppa social batch 
  --site-id <id> 
  --file social-calendar.json

Where social-calendar.json:

[
  {
    "platform": "twitter",
    "content": "Post text...",
    "scheduled_at": "2026-04-01T10:00:00Z"
  },
  {
    "platform": "linkedin",
    "content": "Post text...",
    "scheduled_at": "2026-04-01T14:00:00Z",
    "image_url": "https://..."
  }
]

Generate a Video

Replicate models (needs Replicate API key in Team Settings):

cuppa video create 
  --prompt "Slow dolly-in on a steaming espresso shot, warm cinematic lighting" 
  --model replicate:runway-gen-4.5 
  --duration 5 
  --aspect-ratio 16:9

Higgsfield DoP via WaveSpeed (image-to-video, needs WaveSpeed API key - get one at wavespeed.ai/accesskey):

cuppa video create 
  --prompt "Vertigo zoom revealing the city skyline behind, anamorphic flare" 
  --model wavespeed:higgsfield-dop-i2v 
  --start-image-url "https://your-cdn.com/hero.jpg" 
  --duration 5 
  --aspect-ratio 16:9

Poll status:

cuppa video status <video-id>

Share a Video to Social

cuppa social share-video 
  --site-id <id> 
  --video-id <video-id> 
  --platform tiktok 
  --content "Check out our latest tips!" 
  --schedule-at "2026-04-15T18:00:00Z"

Publish and Schedule

# Publish immediately
cuppa social publish 
  --site-id <id> 
  --platform twitter 
  --content "New blog post!" 
  --media-url "https://example.com/image.jpg"
 
# Schedule for later
cuppa social schedule 
  --site-id <id> 
  --platform linkedin 
  --content "Industry insights..." 
  --media-url "https://example.com/image.jpg" 
  --scheduled-at "2026-04-20T09:00:00Z"

Schedule or Publish Draft Posts

Draft social posts from the content planner can be scheduled or published directly:

# Schedule a single draft post (uses the post's scheduled_at time)
cuppa social posts schedule-draft <post-id>
 
# Publish a single draft post immediately
cuppa social posts publish-draft <post-id>
 
# Bulk schedule all drafts for a date
cuppa social posts schedule-drafts --date 2026-04-01
 
# Bulk schedule all drafts for a site + platform
cuppa social posts schedule-drafts --site-id <id> --platform linkedin
 
# Bulk schedule specific posts by ID
cuppa social posts schedule-drafts --post-ids "id1,id2,id3"
 
# Bulk publish instead of schedule
cuppa social posts schedule-drafts --post-ids "id1,id2" --action publish

Social Inbox

Manage comments and DMs from connected accounts (Power plan and above):

# List inbox items (filter by site, platform, type, unread)
cuppa social inbox list --site-id <id> --unread
 
# Reply to a comment or DM
cuppa social inbox reply <item-id> --message "Thanks for reaching out!"

Paid Ads

View campaigns and ads from Meta, Google, TikTok, LinkedIn, Pinterest, and X, or boost published posts into paid ads on your own ad account (Power plan and above):

# List connected ad accounts (use --refresh to pull the latest from Zernio)
cuppa social ads accounts --site-id <id> --refresh
 
# List live campaigns (optional platform/date filters)
cuppa social ads campaigns --site-id <id> --platform google --from-date 2026-06-01
 
# List ads with metrics (filter by platform, ad account, or campaign)
cuppa social ads list --site-id <id> --platform facebook --campaign-id <platform-campaign-id>
 
# Boost a published post
cuppa social ads boost 
  --post-id <published-post-id> 
  --ad-account-id <platform-ad-account-id> 
  --platform instagram 
  --name "Spring promo" 
  --goal traffic 
  --budget 25 --budget-type daily

Platform filter values for campaigns and list: facebook, instagram, google, tiktok, linkedin, pinterest, twitter.

PR Radar

Find breaking news your brand can credibly weigh in on, then draft pitches (Power plan and above):

# Scan a site for PR opportunities
cuppa pr scan --site-id <id>
 
# List detected opportunities (filter by status)
cuppa pr opportunities --site-id <id> --status pitch_ready
 
# Generate a pitch email for an opportunity (optionally find journalists)
cuppa pr pitch <opportunity-id> --journalists
 
# Brand PR contacts (journalists/editors)
cuppa pr contacts list --site-id <id>
cuppa pr contacts create --site-id <id> --name "Jane Reporter" --outlet "TechCrunch" --email jane@example.com
cuppa pr contacts save <opportunity-id>          # save all journalists from an opportunity
cuppa pr contacts verify <contact-id> [<id>...]  # verify emails (Kickbox)
cuppa pr contacts delete <contact-id>

Slack Commands

Run or propose the same commands as /cuppa in Slack — useful for scripts and agents when you want results posted to a channel. Requires Slack connected at Team Settings → Integrations. See Slack Integration for @Cuppa mentions and approval cards.

cuppa slack run "generate keyword=\"best coffee makers\" site=cuppa.ai"
cuppa slack run "status" --channel C0123456789
cuppa slack propose "bulk keywords=\"a, b, c\" site=cuppa.ai" --channel C0123456789

Wrap the command in quotes. Do not include the /cuppa prefix.

Sites & Clusters

List sites (domain lookup)

Large teams: resolve a brand by exact domain or substring instead of paging through every site.

cuppa site list --domain homerocketrealty.com
cuppa site list --search coffee --limit 20
cuppa site list --page 1 --limit 50 --status active

GET /v1/sites returns X-Total-Count, X-Page, X-Limit, and X-Has-More headers.

Generate a content cluster

Cuppa auto-derives interlink URLs as https://{domain}/{slug}/ when the site has no Link Engine URL pattern. Override with --url-pattern (must include {slug}).

cuppa cluster generate \
  --site-id <uuid> \
  --pillar "main topic keyword" \
  --keywords "supporting kw 1, supporting kw 2" \
  --url-pattern "https://example.com/blog/{slug}/"

Brand Performance Commands

Quick Health Check

cuppa performance overview --site-id <id>

Shows KPIs (combined organic clicks and impressions from Google + Bing when connected, CTR, AI citations, social reach), Brand Visibility Score, and Quick Wins. Organic totals include Bing when a Bing property is bound to the brand.

Content Health

cuppa performance content-health --site-id <id> --limit 10

Shows top pages, content decay, striking distance keywords, and keyword cannibalization.

AI Visibility

cuppa performance ai-visibility --site-id <id> --days 30

Shows LLM mentions (ChatGPT, Google AI Overview), top prompts citing your brand, and citation gaps vs competitors.

Backlinks

cuppa performance backlinks --site-id <id>

Shows domain rating, backlink stats, and top referring domains (requires Ahrefs connection).

Full Brand Brief

cuppa performance brief --site-id <id>

Combines all of the above into a single comprehensive brand performance report. This is the recommended starting point before generating content.

GSC Queries

cuppa performance queries --site-id <id> --limit 20 --sort clicks

Bing Performance

cuppa perf bing --site-id <id> --limit 20

Shows Bing Webmaster totals, top queries, and top pages. Use alongside cuppa performance overview (combined Search KPIs) to compare engines.

Content Planner Events

List Events

cuppa planner events list --site-id <id> --from-date 2026-04-01 --to-date 2026-04-30

Create Custom Event

cuppa planner events create 
  --site-id <id> 
  --title "Product Launch: Summer Collection" 
  --event-date 2026-06-01 
  --event-type product_launch 
  --recurrence none

Delete Event

cuppa planner events delete <event-id>

Using the CLI with AI Agents

The CLI is designed to work with AI coding assistants like Claude Code, Cursor, and similar tools. Your AI agent can call any cuppa command and parse the JSON output.

JSON output for agents

All commands support --format json for machine-readable output:

cuppa content list --format json
cuppa site brand abc123 --format json
cuppa research serp --keyword "content marketing" --format json

Example agent workflow

An AI agent managing a brand could:

# Check current status
cuppa status --format json
 
# Research keywords
cuppa research keywords --keyword "content marketing" --format json
 
# Generate articles for top opportunities
cuppa generate "content marketing strategy 2026"
 
# Check GSC performance
cuppa performance --period 7d --format json
 
# Optimize articles that dropped in ranking
cuppa optimize <article-id>
 
# Run a research agent to find content gaps
cuppa agent run <agent-id>
 
# Review the agent's findings
cuppa agent get <agent-id> --format json

The agent composes these primitives however it needs to. There is no limit to how commands can be combined.

Configuration

Config file location

~/.cuppa/config.json

Config values

Environment variables

Environment variables override config file values:

Plan Requirements

The CLI uses the same feature gating as the Cuppa web app:

Troubleshooting

“API key not configured” Run cuppa auth login and paste your API key, or set CUPPA_API_KEY as an environment variable.

“Access denied. Please upgrade your plan” The feature you are trying to use requires a higher plan. Check the plan requirements table above.

“Site ID required” Run cuppa init to set a default brand, or pass --site-id <id> to the command.

Command hangs or times out Some operations (bulk generation, campaign creation) take time. Use cuppa watch <id> to monitor progress.

JSON parsing errors from your agent Make sure you are passing --format json to get structured output instead of table format.

Everything syncs with Cuppa UI

All content created via the CLI is stored in your Cuppa account. Articles, images, social posts, videos, and planner items created from the CLI appear in the Cuppa web app immediately. Edit in the CLI, review in the UI. Or vice versa.

Also Available

• MCP Server: Use Cuppa inside AI editors (Cursor, Claude Desktop, Windsurf)
• CLI vs MCP vs API: Comparison guide to choose the right interface

Need Help?

• Documentation: learn.cuppa.ai
• Support: hello@cuppa.ai
• API Reference: cuppa.ai/static/cuppa-api-v1.yaml