# 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)

```bash
npm install -g @cuppa-ai/cli
```

After installation, the `cuppa` command is available globally:

```bash
cuppa --version
```

#### Option 2: Run without installing

```bash
npx @cuppa-ai/cli --help
```

#### Option 3: Install from source

```bash
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](https://app.cuppa.ai/team/settings/api/keys)
2. Click **Create Key**
3. Copy the key (you will not see it again)

#### Step 2: Authenticate the CLI

```bash
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:

```bash
export CUPPA_API_KEY="your-key-here"
```

#### Step 3: Initialize your default brand

```bash
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

```bash
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

```bash
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

```bash
cuppa performance --period 30d
```

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

#### Optimize an existing article

```bash
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

```bash
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

```bash
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, analytics    |
| `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, strategy settings, automation     |
| `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:

```bash
cuppa --help
cuppa content --help
cuppa content create --help
```

***

### Social Media Commands

#### Generate for One Platform

```bash
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

```bash
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:

```bash
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

```bash
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

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

Where `social-calendar.json`:

```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://..."
  }
]
```

#### Share a Video to Social

```bash
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

```bash
# 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:

```bash
# 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
```

***

### Brand Performance Commands

#### Quick Health Check

```bash
cuppa performance overview --site-id <id>
```

Shows KPIs (organic clicks, impressions, CTR, AI citations, social reach), Brand Visibility Score, and Quick Wins.

#### Content Health

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

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

#### AI Visibility

```bash
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

```bash
cuppa performance backlinks --site-id <id>
```

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

#### Full Brand Brief

```bash
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

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

***

### Content Planner Events

#### List Events

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

#### Create Custom Event

```bash
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

```bash
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:

```bash
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:

```bash
# 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.

***

### 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](https://learn.cuppa.ai)
* **Support**: <hello@cuppa.ai>
* **API Reference**: [cuppa.ai/static/cuppa-api-v1.yaml](https://cuppa.ai/static/cuppa-api-v1.yaml)