Developers/CLI/CLI

Things Worth Scripting With the Cheerful CLI

Five tasks where a command genuinely beats the web app, with the exact commands. Each one is a real command with real flags — run any of them bare first to see the response shape before you write the jq around it.

Two of these five write. They are marked, and the marking is not decoration: rules bulk-edit changes what every future draft on that campaign is generated against.

The Cheerful CLI can export a campaign, list every thread waiting on a human, and pull post-tracking metrics in one command each, which is what makes it worth scripting.

Export a campaign’s creators and its numbers

Two commands, both of which write a file and neither of which touches the campaign. This is the fastest way to get campaign data in front of someone who will never log in.

cheerful campaigns list --pretty            # find the campaign id
cheerful creators export  --campaign-id <id> --output creators.csv
cheerful analytics export --campaign-id <id> --output analytics.csv

Read-only. --output is required on both, so nothing is written to a path you did not name.

Find every thread waiting on a human

The question the inbox is worst at answering when it is busy: what is actually blocked on me? Thread status is the honest filter, and it takes several at once.

# drafts ready for review, plus anything explicitly waiting on review
cheerful threads list \
  --status DRAFT_READY,WAITING_FOR_DRAFT_REVIEW \
  --limit 100 --pretty

# scoped to one campaign
cheerful threads list --campaign-id <id> --status DRAFT_READY --pretty

The statuses the flag accepts are WAITING_FOR_DRAFT_REVIEW, IGNORE, DONE, UNREAD, DRAFT_READY and RESPONDED. Read-only.

A morning health check

Four read commands that answer "is anything wrong" faster than opening four tabs. Worth putting in a shell function; not worth putting in cron, because the CLI cannot sign itself in.

cheerful auth whoami                       # acting as the right account?
cheerful campaigns list --status active --pretty
cheerful inbox list --tab pending --limit 10 --pretty
cheerful integrations status --pretty      # anything disconnected?

All read-only. The integrations check is the one that catches the failure people notice last — a mailbox or a Sheet that quietly stopped being connected.

Bulk-edit a campaign’s brief — this one writes

Rules are what drafts are generated against, so this is the highest-leverage write on the whole surface and the one most worth being careful with.

cheerful rules list --campaign-id <id> --pretty     # read first
cheerful rules bulk-edit --campaign-id <id> --rules "..."

Read before you write, and keep the shape. The rules field is free text that the drafting model reads as written, separated into paragraphs rather than lines. Rewriting it line-by-line — the way you would edit a list — collapses paragraphs into one another and changes the brief in ways that are invisible until a draft comes back wrong. Print the current value, edit it as prose, and pass the whole thing back.

There is no undo. The previous value is not kept anywhere you can reach from the CLI, so if the campaign matters, save the output of rules list before you overwrite it.

Pull post-tracking metrics for a campaign

Post detection runs on its own schedule; this reads what it has found rather than triggering a sweep.

cheerful post-tracking list    --campaign-id <id> --pretty
cheerful post-tracking metrics --campaign-id <id>

# a sweep, if you want one now — this one writes
cheerful post-tracking scan --campaign-id <id>

The first two are read-only. scan starts real work and costs what a sweep costs, so it is not a command to loop.

The two things that will bite you

  • The default timeout is 30 seconds. Creator search takes 90–155, so cheerful creators search without --timeout 200 gives up on a call that was working fine. The failure looks like a broken command rather than an impatient one.
  • **whoami before anything that writes.** The CLI holds one signed-in account with no profile switch, so on a shared machine the account you are acting as is whoever signed in last.

What this does not do

  • None of these run unattended. Sign-in needs a browser, so a cron job or a CI step will fail the first time the session needs refreshing.
  • rules bulk-edit, post-tracking scan and anything named create/update/delete/launch/send are real writes with no undo.
  • Response shapes are not printed here on purpose — run a command bare once and read its JSON rather than trusting a field list that could be stale.
  • Flags shown are current as of the version named on the commands page; --help is authoritative.

Frequently asked questions

Can I schedule these with cron?
No. The CLI signs in through a browser, so an unattended session will fail when it needs refreshing.
Which of these commands write?
rules bulk-edit and post-tracking scan. The exports, the thread and inbox listings, the health check and the metrics read are all read-only.
Why did my creator search time out?
The default request timeout is 30 seconds and a search takes 90–155. Pass --timeout 200.
How do I undo a rules bulk-edit?
You cannot from the CLI. Save the output of cheerful rules list before overwriting, and edit the value as prose rather than line-by-line.

Run your next campaign
on Cheerful

From first hello to signed agreement — see how much of the work disappears.

Get started free