# CLI Read Me

## @cuppa-ai/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.

### Install

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

### Setup

```bash
# Authenticate with your API key
cuppa auth login

# Select your default brand
cuppa init

# Verify
cuppa status
```

Get your API key from [Team Settings > API Keys](https://app.cuppa.ai/team/settings/api/keys).

### Quick Start

```bash
# Generate an article with auto-grading
cuppa generate "best project management tools"

# Check GSC performance
cuppa performance --period 30d

# Optimize an underperforming article
cuppa optimize <article-id>

# Publish to CMS + social
cuppa publish <article-id> --platform ghost --social linkedin,twitter

# Full multi-asset campaign
cuppa campaign create --type mixed --images 5 --videos 3 --articles 2 --social instagram,linkedin --publish

# Bulk local SEO pages
cuppa seo local --service "roof repair" --locations cities.txt --research-serps
```

### Commands

#### Workflow Commands

| 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

`auth` `meta` `content` `project` `site` `image` `social` `video` `preset` `knowledge` `cluster` `planner` `research` `links` `template` `agent` `mood-board` `brand` `chat` `page`

Run `cuppa <command> --help` for details on any command.

### Using with AI Agents

The CLI works with Claude Code, Cursor, and any AI assistant with terminal access. All commands support `--format json` for structured output:

```bash
cuppa content list --format json
cuppa performance --period 7d --format json
```

Your AI agent can compose primitives into any workflow. Research, generate, optimize, publish, and monitor, all from one terminal session.

### Configuration

Config file: `~/.cuppa/config.json`

Environment variables override config:

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

### Requirements

* Node.js 20+
* Cuppa account (Solo plan or above)
* API key from [app.cuppa.ai](https://app.cuppa.ai/team/settings/api/keys)

### Links

* [Documentation](https://learn.cuppa.ai/getting-started/cli)
* [API Reference](https://cuppa.ai/static/cuppa-api-v1.yaml)
* [Cuppa AI](https://cuppa.ai)

### License

MIT