# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.cuppa.ai/rest-api/cli-read-me.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.