Run Cheerful From Your Terminal
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, 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#
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$ Every command takes --pretty for a human-readable table and --timeout <seconds> when a call is slow — creator search genuinely takes 90–155 seconds, 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.
# 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 --prettyWhat is in it#
Twenty-five command groups and 176 commands. The full reference is on the commands page; 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 createandrules bulk-editall 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.
- Creator search takes 90–155 seconds and the default request timeout is 30. Pass
--timeout 200or 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 creator search takes 90–155. 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.