CLI

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)

Command	Description
cuppa init	Interactive setup, select default brand
cuppa status	Brand dashboard overview
cuppa generate <keyword>	Create + poll + grade in one shot
cuppa optimize <id>	Grade + SERP research + optimize + re-grade
cuppa publish <id>	Publish to CMS + generate social posts
cuppa campaign create	Multi-asset campaign generation
cuppa performance	GSC keyword rankings snapshot
cuppa watch <id>	Poll generation status with live progress
cuppa seo local	Bulk local SEO service pages
cuppa seo programmatic	Programmatic pages from CSV + template
cuppa seo audit	SERP research + gap analysis

Resource Commands (CRUD primitives)

Command Group	Description
cuppa auth	Login, logout, status
cuppa content	Create, list, get, update, grade, optimize, publish
cuppa project	Bulk generation projects
cuppa site	Brand/site management, Brand DNA, visual style
cuppa image	Generate images, bulk image generation
cuppa social	Generate, publish, schedule, carousel
cuppa video	Script generation, video creation
cuppa preset	Content presets (reusable generation configs)
cuppa knowledge	Knowledge base management
cuppa cluster	Content clusters
cuppa planner	Content calendar management
cuppa research	Keyword research, SERP analysis, competitors
cuppa links	Link Engine management
cuppa template	Custom page templates
cuppa agent	Research agents (list, get, run)
cuppa mood-board	Mood board management
cuppa brand	Brand notebook entries
cuppa chat	AI chat completions
cuppa meta	Available models, languages, regions

Getting Help

Every command has built-in help:

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

---

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

Key	Description	Set by
api_key	Your Cuppa API key	cuppa auth login
base_url	API base URL (default: https://app.cuppa.ai)	Manual edit
default_site_id	Default brand/site ID	cuppa init
default_site_name	Default brand name (display only)	cuppa init
default_format	Default output format (json or table)	Manual edit

Environment variables

Environment variables override config file values:

Variable	Description
CUPPA_API_KEY	API key
CUPPA_BASE_URL	API base URL
CUPPA_SITE_ID	Default site ID

---

Plan Requirements

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

Feature	Minimum Plan
Content generation	Solo
Social publishing	Solo
Image generation	Solo
Content grading	Power
SERP analysis	Power
Knowledge Bases	Power
Research agents	Power
Link Engine	Business
API access	Solo

---

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.

---

Need Help?

• Documentation: learn.cuppa.ai

• Support: [email protected]

• API Reference: cuppa.ai/static/cuppa-api-v1.yaml