HeyCMO

CLI quick start

The heycmo command line does from a terminal or a CI job what an agent does over MCP. It starts and follows jobs and asks to publish. A person approves each piece on app.heycmo.ai.

Run it

You need Node.js 24 or later. Run any command with npx:

npx heycmo --help

The examples below write heycmo for short.

1. Audit a site, with no account

heycmo audit frontguard.dev

You get a score out of 100 for Google search, AI search and readiness for AI agents. You also get the top fixes and a link to the public score page. In CI, --min-score 70 makes the command fail when the score is lower.

2. Sign in

Pick one of these:

Then check who you are and pick a workspace:

heycmo whoami
heycmo workspaces list
heycmo workspaces use ws_8f3k2m

A heycmo login holds agent scopes only, is capped at level L2 (Ask first) and never pays. An API key holds the scopes and level cap the owner set, and a CI key is fixed at L1, so a live write with a CI key answers level_too_low.

3. Start a job and follow it

heycmo jobs list
heycmo runs estimate seo_article --input format=comparison --input competitor=billowpay.example
heycmo runs create seo_article --input format=comparison --input competitor=billowpay.example --wait
heycmo runs events run_7h2k9d --follow

The estimate says what the run uses from your plan, for example "Uses 1 of your 8 new pages. 5 left in January.", and starts nothing. A new workspace starts with the knowledge base: heycmo runs create knowledge_base --input mode=build. Most jobs answer kb_not_ready until it is built.

--wait waits until the run ends or needs a person. It exits 0 when the run succeeded and nothing waits, 4 when the run or its draft waits for a person (it prints the link), 1 when the run failed or was canceled, and 124 after --timeout. In a script with set -e, expect exit 4 after a draft. Each start sends an idempotency key, so the same start sent again makes one run.

4. Read the drafts

heycmo artifacts list --run run_7h2k9d
heycmo artifacts get art_4n8q1z --format md

To edit a draft, save a new version from a file: heycmo artifacts version art_4n8q1z --file draft.md. To send in your own draft, use heycmo artifacts create --file draft.md --title "...". HeyCMO checks every claim against the knowledge base, and a person approves it before it posts.

5. Ask to publish

heycmo connections list
heycmo publish art_4n8q1z --to con_x0001 --at 2027-01-18T09:00:00+01:00

The command prints the approval link and exits 4. Give the link to a person. They approve on app.heycmo.ai with a passkey (Face ID, fingerprint or your phone), and HeyCMO posts the piece at that time after a last check. Follow it with heycmo actions list and heycmo approvals list.

Lower a level or pause

heycmo autonomy show
heycmo autonomy set publish L1
heycmo autonomy pause

Lowering and pausing apply at once. Raising a level with autonomy set prints the app.heycmo.ai link and exits 4. There is no resume command: a person resumes on app.heycmo.ai, and a command refused by a paused workspace exits 4.

Output for scripts

Settings

VariableWhat it sets
HEYCMO_TOKENThe token to use. It wins over a stored login.
HEYCMO_WORKSPACEThe workspace, when --workspace is not given.
HEYCMO_CLIENT_IDThe CLI client ID for heycmo login.
HEYCMO_API_URLThe API address. The default is https://api.heycmo.ai. Use https; plain http works only on 127.0.0.1 or localhost.
HEYCMO_AUTH_URLThe sign-in address. The default is https://auth.heycmo.ai.
HEYCMO_CONFIG_DIRWhere the CLI keeps its login and settings. The default is $XDG_CONFIG_HOME/heycmo, else ~/.config/heycmo.

Exit codes

CodeMeaning
0Done.
1The request failed. The message, or the problem in --json output, says why. See the error codes.
2The command or its input is not valid (invalid_request).
3Sign-in needed (unauthenticated). Run heycmo login, or set HEYCMO_TOKEN.
4A person must act. The command prints the app.heycmo.ai link to give them.
5Too many requests (rate_limited). Wait, then try again.
124--wait reached its timeout and the run is still going.

What only a person can do

No command does these things. A person does them on app.heycmo.ai, most often with a passkey. A command that reaches one prints the link and exits 4.