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:
- On your own computer:
heycmo login. It prints a code and a link onauth.heycmo.ai. Open the link, sign in and enter the code. This login needs the CLI client ID inHEYCMO_CLIENT_ID; ask HeyCMO for it. - In CI or a script: a workspace owner makes an API key on
app.heycmo.ai. Put it in your secret store and setHEYCMO_TOKEN, or pipe it in once:printf %s "$TOKEN" | heycmo login --with-token. - For a new workspace:
heycmo signup --email ana@frontguard.dev --domain frontguard.dev --invite <code>. Until Apr 26, 2027 this needs an invite code. The person gets a claim link by email and owns the workspace when they open it.
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
--jsonprints JSON on standard output. The CLI also prints JSON when standard output is not a terminal, for example in a pipe. Messages for people go to standard error. With--json, the result keeps the credit fields.--dry-runshows the request a write would send, and changes nothing.-w <ws>(or--workspace) picks the workspace for one command.heycmo schema <command>prints the JSON Schemas of a command's input and output. It needs no sign-in.
Settings
| Variable | What it sets |
|---|---|
HEYCMO_TOKEN | The token to use. It wins over a stored login. |
HEYCMO_WORKSPACE | The workspace, when --workspace is not given. |
HEYCMO_CLIENT_ID | The CLI client ID for heycmo login. |
HEYCMO_API_URL | The API address. The default is https://api.heycmo.ai. Use https; plain http works only on 127.0.0.1 or localhost. |
HEYCMO_AUTH_URL | The sign-in address. The default is https://auth.heycmo.ai. |
HEYCMO_CONFIG_DIR | Where the CLI keeps its login and settings. The default is $XDG_CONFIG_HOME/heycmo, else ~/.config/heycmo. |
Exit codes
| Code | Meaning |
|---|---|
0 | Done. |
1 | The request failed. The message, or the problem in --json output, says why. See the error codes. |
2 | The command or its input is not valid (invalid_request). |
3 | Sign-in needed (unauthenticated). Run heycmo login, or set HEYCMO_TOKEN. |
4 | A person must act. The command prints the app.heycmo.ai link to give them. |
5 | Too 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.
- Approve or reject a piece, or a week of pieces.
- Stop a scheduled post.
- Raise a level or resume a paused workspace.
- Finish a connection:
heycmo connect githubonly prints the link. - State a fact, mark a fact wrong, or change the tracked questions.
- Make or revoke API keys, invite members, and anything about the plan or invoices.