# Run Cheerful from your terminal

> The Cheerful CLI: install with npm, sign in through the browser, and drive campaigns, creator search, the inbox, drafts and reporting from a terminal. JSON output by default, so every command pipes.

The Cheerful CLI is a native binary published to npm. Install it, sign in through your browser, and the same work you do in the web app — campaigns, creator search, the inbox, drafts, rules, gifting orders, reporting — is available as commands. Output is JSON by default, so anything you can ask for you can pipe into `jq` or a script.

Unlike the MCP connector, whose tools read data (apart from a paid creator search and saving creators to your own lists), **the CLI is not read-only.** It calls the same API the web app calls, which means `campaigns launch` launches and `email send` sends. That is the point of it, and it is also the reason to treat a signed-in terminal the way you treat a logged-in browser tab.

The Cheerful CLI runs campaigns, creator search, the inbox and reporting from your terminal, with JSON output by default so every command pipes into a script.

## How to set it up

### 1. Install it

npm install -g @cheerful/cli. The install pulls a native binary for your platform — macOS on Apple Silicon or Intel, Linux x64, or Windows x64.

### 2. Sign in

cheerful auth login opens your browser, signs you in to Cheerful, and hands the session back on a local callback. There is no API key to paste; see the sign-in page for why.

### 3. Check what you are acting as

cheerful auth whoami prints the account the CLI is using. Do this before anything that writes, especially on a machine where more than one person has signed in.

## The first five commands

```bash
npm install -g @cheerful/cli
cheerful auth login              # browser sign-in, no key
cheerful auth whoami             # which account am I?
cheerful campaigns list --pretty # a table instead of JSON
cheerful inbox list --tab pending --limit 20
```

_Nothing here writes. The fifth is the one you will run most._

_(The HTML version of this page shows an animated example of this exchange, including the read-only tool chips.)_

Every command takes `--pretty` for a human-readable table and `--timeout <seconds>` when a call is slow — a smart creator search genuinely takes about a minute, and the default 30-second timeout will give up on it.

## JSON by default, and why that is the right default

A bare command prints JSON. That is deliberate: the CLI is most useful as a thing other things call, and a tool whose default output is a pretty table forces every script through a parser that breaks the first time a column is added. `--pretty` is there for when you are the one reading.

```bash
# how many campaigns are active?
cheerful campaigns list --status active | jq 'length'

# every thread waiting on a human, newest first
cheerful threads list --status DRAFT_READY,WAITING_FOR_DRAFT_REVIEW --limit 100

# the same thing, readable
cheerful threads list --status DRAFT_READY --pretty
```

_Run a command bare once to see its response shape before writing the jq for it._

## What is in it

Twenty-five command groups and 176 commands. The full reference is on [the commands page](/docs/cli/commands); this is the shape of it.

| Area | Groups |
| --- | --- |
| Campaigns and creators | `campaigns` `creators` `lists` `csv` |
| Replies and drafts | `threads` `inbox` `drafts` `email` `signature` |
| How the agent behaves | `rules` `faq` `automations` |
| Connections | `auth` `integrations` `gmail` `sheet` |
| Gifting and results | `orders` `goaffpro` `post-tracking` `analytics` |
| Operational | `temporal` `workflows` `schema` `config` `ssr` |

The last row is internal tooling that ships in the same binary — Temporal workflow inspection, the embedded workflow schema, CLI configuration, and a synthetic-consumer panel that is experimental. They are not documented page-by-page because they are operational surfaces rather than product, and `cheerful <group> --help` is the honest reference for them.

## Which platforms it runs on

| Platform | Architecture | Package |
| --- | --- | --- |
| macOS | Apple Silicon (arm64) | `@cheerful/cli-darwin-arm64` |
| macOS | Intel (x64) | `@cheerful/cli-darwin-x64` |
| Linux | x64 | `@cheerful/cli-linux-x64` |
| Windows | x64 | `@cheerful/cli-win32-x64` |

The top-level package picks the right one through npm’s optional dependencies, so `npm install -g @cheerful/cli` is all you run. **There is no Linux arm64 build**, which matters if you were hoping to run this on a Raspberry Pi or an arm64 cloud instance.

## Where its configuration lives

`cheerful config show` prints the config file path and the API host in use. The session is refreshed automatically; `cheerful auth logout` ends it, and deleting the file does the same thing.

One account at a time. There is no profile switch, so a shared machine with two Cheerful users is a `whoami` before every write rather than a configuration option.

## What this does not do

- **Not read-only.** `campaigns launch`, `email send`, `drafts generate`, `orders create` and `rules bulk-edit` all do the real thing, against your real account, and spend real credits.
- Sign-in needs a browser, so the CLI does not work unattended — no CI, no cron, no headless runner. The session also expires and needs a browser again.
- One signed-in account at a time. No profiles, no service identity, no way to act as a team rather than a person.
- macOS arm64 and x64, Linux x64, Windows x64 only. No Linux arm64.
- A CLI session carries exactly your own permissions, so it cannot reach a teammate’s campaign that has not been shared with you.
- A smart creator search takes about a minute and the default request timeout is 30. Pass `--timeout 200` or it gives up on a call that was working.

## Frequently asked questions

**How do I install the Cheerful CLI?**

npm install -g @cheerful/cli, then cheerful auth login. The install pulls a native binary for macOS, Linux or Windows.

**Do I need an API key?**

No. cheerful auth login signs you in through the browser. Cheerful does not issue API keys at all.

**Is the CLI read-only like the MCP connector?**

No. It calls the same API the web app calls, so it can create and launch campaigns, send email and spend credits.

**Can I run it in CI?**

Not today. Sign-in requires a browser, so a build agent cannot complete it.

**Why does my command time out?**

The default request timeout is 30 seconds and a smart creator search takes about a minute. Pass --timeout 200.

**How do I get a table instead of JSON?**

Add --pretty. JSON is the default because the CLI is most useful as something a script calls.

**Which platforms are supported?**

macOS on Apple Silicon and Intel, Linux x64, and Windows x64. There is no Linux arm64 build.

## Keep reading

- [Every CLI command](https://www.cheerful.ai/docs/cli/commands)
- [Things worth scripting](https://www.cheerful.ai/docs/cli/recipes)
- [Sign in to the Cheerful CLI](https://www.cheerful.ai/docs/api-keys)
- [Connect Cheerful to Claude and ChatGPT](https://www.cheerful.ai/docs/mcp)

---

Canonical HTML: https://www.cheerful.ai/docs/cli