# Sign in to the Cheerful CLI and connector

> Cheerful does not issue API keys. The CLI and the MCP connector both authenticate through a browser sign-in with your own account — here is how that works, and what it means for scripts and CI.

There is no API key to generate. Cheerful does not issue static keys, and both machine-facing surfaces — the CLI and the MCP connector — sign you in through your browser instead, as yourself. If you arrived here from the CLI’s setup instructions looking for a key to paste, this page is the whole answer: run `cheerful auth login` and you are done.

Cheerful authenticates the CLI and the MCP connector through a browser sign-in with your own account rather than a static API key, so a machine session carries exactly the permissions the person behind it has.

## How to set it up

1. **Install the CLI** — npm install -g @cheerful/cli. It pulls a native binary for macOS, Linux or Windows.
2. **Sign in** — cheerful auth login opens your browser, signs you in to Cheerful, and hands the token back to the CLI on a local callback. Nothing is copied and pasted.
3. **Confirm it worked** — cheerful auth whoami prints the account the CLI is acting as. If that is the wrong account, sign out and sign in again rather than editing config by hand.

## Why there is no key

A static API key is a credential that outlives the person who created it, carries whatever permissions it was minted with, and cannot be told apart from any other holder of the same string. For a product whose account boundary is "the campaigns and mailboxes this person may see", that is a worse fit than it first looks: a key shared across a team quietly becomes an account nobody owns, and a key that leaks is indistinguishable from its owner.

So Cheerful authenticates machines the same way it authenticates people. The CLI signs you in through the browser and holds a session; the MCP connector runs a standard OAuth flow and holds a token issued to that specific client for your account. Both carry your permissions exactly — no more, and no less — and both stop working when your session is revoked.

## What that means for scripts

A browser sign-in works on your own machine and does not work on a build agent. That is a real limit rather than a detail: unattended use — CI, cron, a shared runner with no browser — is not supported today. The CLI is built for interactive work at a terminal, and a scheduled job that shells out to it will fail the first time its session needs refreshing.

If that is what you need, say so. Machine credentials are a design question with real consequences for a product that holds other people’s inboxes, and the version worth building is the one shaped by what people are actually trying to automate. [Get in touch](/about) with the job you are trying to run.

## What a signed-in session can reach

A CLI session and a connector token both carry your own permissions, and that is the whole security model: there is no elevated machine scope, and no way to grant a script more than the person running it has. In practice that means a session reaches your own campaigns, lists and mailboxes, plus anything your teams share with you — and reaches nothing else.

It also means the answer to "why can’t this script see that campaign" is usually an access answer rather than a bug. The connector’s `account_read` tool and the CLI’s `cheerful auth whoami` both report which account is acting and what it is entitled to, which is the fastest way to tell a permissions problem from a broken call.

Most connector tools only read data, so the worst a leaked connector token can do is read, spend credits on creator search, add creators to your own lists, or change a campaign draft. **A CLI session is not read-only** — it can create and launch campaigns, send email and spend credits, because it drives the same API the web app does. So the honest asymmetry is: connect the connector freely, and treat a signed-in terminal the way you would treat a logged-in browser tab.

## If you are integrating Cheerful with something else

A key is often the wrong question. If the goal is to get Cheerful’s data in front of an assistant, [the MCP connector](/docs/mcp) already does that with no credential to manage. If the goal is to move campaign state into a spreadsheet or a project tool, the [built-in integrations](/integrations) — Google Sheets, Airtable, Monday, Shopify, Slack — write that data on a schedule without anything to script.

What remains genuinely unsolved is unattended automation against your own account: a nightly export, a health check, a scheduled report. That is the case machine credentials would exist for, and it is the one worth telling us about.

## Where the sign-in is stored

The CLI keeps its session in a config file in your home directory and refreshes it automatically. `cheerful config show` prints where that is and which API host it is talking to. Deleting it signs you out; so does `cheerful auth logout`.

The MCP connector stores nothing on your machine at all — the token lives in whichever client you connected, and removing the connector there is what revokes it.

## What this does not do

- There is no self-serve API key, and no key issued on request. Static keys are not an authentication mechanism on this product.
- Unattended and headless use is not supported: both surfaces need a browser once to sign in, and the CLI needs one again when its session expires.
- The CLI acts as one account at a time. There is no way to run it as a service identity or as a team rather than as a person.
- A CLI session carries your own permissions, so it cannot reach a teammate’s campaign that has not been shared with you.

## Frequently asked questions

**How do I get a Cheerful API key?**

You do not — Cheerful does not issue API keys. Run cheerful auth login for the CLI, or add the MCP server as a connector and sign in there. Both authenticate you as yourself.

**Can I run the CLI in CI?**

Not today. Sign-in requires a browser, so a build agent cannot complete it. Tell us what you are trying to automate and it will shape what we build.

**What happened to the --api-key flag?**

Static API keys were removed as an authentication mechanism. The flag may still exist in older CLI builds, but the API no longer accepts a key, so browser sign-in is the only path.

**Where does the CLI store its session?**

In a config file in your home directory, refreshed automatically. cheerful config show prints the location and the API host in use.

**Does the MCP connector need a key?**

No. It uses OAuth 2.1 — your client sends you to a Cheerful sign-in and receives a token scoped to your account.

## Keep reading

- [Connect Cheerful to Claude and ChatGPT](https://www.cheerful.ai/docs/mcp)
- [Every tool the connector exposes](https://www.cheerful.ai/docs/mcp/tools)
- [Developers](https://www.cheerful.ai/docs)

---

Canonical HTML: https://www.cheerful.ai/docs/api-keys