Install the CLI

Q: Can I create a Revnu account from the terminal?

Yes. npx -y @revnu/cli setup opens Revnu's sign-in page, which creates the account for someone new, then walks through the website, the research review, checkout and the first start. A coding agent runs the same thing with --json.

Q: What does exit code 4 mean?

LOGIN_PENDING: the person hasn't finished signing in at loginUrl yet. Show them the link and run the same command again once they have. It is not an error to retry.

Q: Can I see what Revnu would do before signing up?

Yes, without the CLI: POST the website to https://revnu.com/api/v1/preview with no token. See Preview a Plan Without an Account.

Q: Where is the token stored?

In ~/.config/revnu/config.json with mode 600, or wherever XDG_CONFIG_HOME points. revnu logout deletes the file but doesn't revoke the token. A token from revnu login is listed in Settings → Developers as "Revnu CLI", with the agent's name when an agent ran it. Signing in again saves a new token in the file. The old one stays live, and when that label is still in use the new one gets a number ("Revnu CLI 2"), so revoke the old one in Settings → Developers.

Q: Can I use it in CI?

Yes. Set REVNU_API_TOKEN as a secret and call the commands directly; nothing is interactive when the token comes from the environment. In CI, setup and login exit 3 rather than wait for a sign-in nobody can do.

The revnu command. Sign up and set up a new account from a terminal or a coding agent with setup --json and its exit codes, then the API routes as subcommands with JSON on stdout.

npx -y @revnu/cli setup      # sign up or sign in, then set Revnu up

revnu setup opens a browser to sign in. Someone new creates their account on the same page, in one click. It then asks for the business's website, shows what Revnu learned with its sources, hands over a Stripe Checkout link and starts Revnu.

To keep the command around:

npm install -g @revnu/cli
revnu login               # browser sign-in; or `revnu auth login` to paste a token
revnu whoami

To connect Revnu to Claude Code, Codex, Gemini CLI, VS Code, Cursor, Claude or ChatGPT as an MCP server instead, MCP Setup and Troubleshooting is the install guide.

revnu login saves its token to ~/.config/revnu/config.json. Or skip the login and set REVNU_API_TOKEN to a token from Settings → Developers. REVNU_API_BASE overrides the API base for testing. Node 20 or later.

Install and maintain coding-agent support

npx -y @revnu/cli setup agent
npx -y @revnu/cli setup agent --check --json
npx -y @revnu/cli setup agent --update

setup agent installs the paired growth skills and user-level MCP connection for detected Claude Code, Codex, Gemini CLI and Cursor hosts. It is separate from revnu setup, which sets up the business account. Restart the coding host, then authenticate Revnu there. Installation itself does not start a paid plan.

The CLI records installed skill-file hashes in a private local management manifest. Updates use a pinned upstream revision and preserve unmanaged or locally edited skills. --adopt records existing files as the baseline without changing them; review custom files before choosing this, because unchanged adopted files become eligible for future upstream replacement. Native plugin installations continue to use the host's plugin update flow.

The paired shell installer records a baseline on new installations and routes later managed repairs through the CLI. Missing or edited files are reported; a successful process exit alone is not treated as a complete global bundle.

Standalone agent installation, update and adoption require macOS, Linux or WSL. On native Windows, install the Revnu plugin in your coding host to receive skills and MCP together. Use user/global scope where offered.

Tooling health describes the standalone global bundle. A working native plugin may not appear there; use its host update flow rather than treating missing standalone files as a broken native plugin.

--check --json returns one JSON object with host-level MCP/skill health, protected skills, managed revision, freshness-check time and a next step. It checks upstream at most once an hour for managed installations. Human CLI help and successful login/account setup expose the same health/update hints on stderr; JSON account setup output stays unchanged. --update applies safe managed updates, and the installed skill can run it as routine maintenance when an upstream update is available. Optional freshness checks never block account setup. --check, --update and --adopt are mutually exclusive.

Tooling commands exit 0 when the bundle is complete, 1 for incomplete setup or an operational error, and 2 for invalid arguments. Operational errors under --json return AGENT_SETUP_FAILED with the blocker and next step. They do not sign in or require an account token. Node/npm and a POSIX shell are required for installation; use the native plugin flow where that environment is absent.

What the person does

Two steps are always the person's: signing in (with Google or a code sent to their email) and entering a card on Stripe's page, when their offer asks for one. Everything else the CLI or a coding agent can run. Card details stay on Stripe's page, never in the CLI. Approving and sending what Revnu drafted goes through revnu review, under the same approval settings as the dashboard.

Set up an account from a coding agent

Claude Code, Codex and Cursor can create and set up an account without loading the MCP server. Run setup with --json: it prints one JSON object on stdout, sends progress to stderr, and never waits for input on stdin.

npx -y @revnu/cli setup --json --website acme.com

Every result carries stage, next (what to do, in words) and command (the command that does it, or null). Follow next until stage is done. The stages are website, researching, review, payment, start and done.

1. The person signs in

With no saved token, setup starts a sign-in in the background, opens a browser if the machine has one, and waits up to 90 seconds (--wait <seconds> changes it). If the person hasn't finished by then, it exits with code 4:

{
  "ok": false,
  "error": "LOGIN_PENDING",
  "message": "Waiting for the person to sign in to Revnu in their browser.",
  "loginUrl": "https://revnu.com/…",
  "browserOpened": true,
  "expiresAt": "2026-10-15T10:15:00.000Z",
  "next": "Ask the person to open loginUrl and sign in; someone new creates their account on the same page, in one click. Then run this command again. …"
}

Show the person loginUrl, wait for them to say they're done, and run the same command again. The link lasts 15 minutes; a re-run inside that time reuses it. If their browser is on another machine, sign-in ends on a page that won't load there. Ask them for that page's address and run revnu login --code '<url>' to finish.

2. Research, then the review

The website goes in and research takes about a minute. Setup waits for it, then stops at stage: "review" with review.rows. Each row has an id, a label, what research found, the sources it came from, and whether it is required. A row with a question is one for the person to answer.

Show the person every row and its sources, and ask what is wrong. These rows become Revnu's memory of the business, so never confirm them on the person's behalf. Then save their answers:

npx -y @revnu/cli setup confirm --json --keep-found \
  --row sells="Invoicing for design agencies" \
  --row neverSay="Never call it accounting software"

--keep-found keeps research's answer for every row you don't pass with --row. --business-name and --extra correct the name and add anything else.

3. Checkout: the person's step

At stage: "payment", the payment object says what the person is signing up for: priceUsdPerMonth, trialDays, freeMonths and cardAtCheckout (whether Stripe's page asks for a card). Offers differ, so read these rather than promising a trial length. Then:

npx -y @revnu/cli setup checkout --json

The result has checkoutUrl. Give it to the person. They open it and finish on Stripe's page themselves; never ask for card details. Running checkout again returns the same link, because a new one would stop the open one working (--new forces a new link). Then wait for the stage to move:

npx -y @revnu/cli setup --json --wait 90

Repeat until stage is start. An account with a YC deal skips checkout: the person adds a card in the dashboard, and next says so.

4. Start

npx -y @revnu/cli setup finish --json

Revnu starts its first work: it researches the market and queues work for approval. If nobody calls finish, it starts on its own 15 minutes after the trial begins. At stage: "done", the person can talk to Revnu with revnu agent message, approve work with revnu review list, or connect Slack, iMessage and their email in the dashboard.

-y takes the safe steps without asking: it makes the checkout link when none is out, and runs finish. It never confirms the review.

Exit codes and error codes

Exit	`error`	Meaning	What to do
0	none	Done; read `stage` and `next`.	Follow `next`.
1	`REJECTED`	Revnu refused a step, such as a website that doesn't exist. `message` says why.	Fix it with the person.
1	`API_ERROR`, `LOGIN_FAILED`, `ERROR`	The API, the network or the sign-in failed.	Retry; `LOGIN_FAILED` starts again with `revnu login`.
2	`USAGE`, `WRONG_STAGE`	A bad flag, or a step that doesn't fit the current stage.	Read `stage` and `next`, then run the right step.
2	`NO_PENDING_LOGIN`	`revnu login --code` ran with no sign-in waiting.	Start one with `revnu login`.
2	`ACCOUNT_HAS_OTHER_BUSINESS`	This login is already set up for another website. Nothing changed.	Follow `next`: sign out and sign in with that business's email.
3	`NOT_AUTHENTICATED`	Not signed in, and nobody can sign in here, such as in CI or with `--no-login`.	A person runs `npx -y @revnu/cli login`, or set `REVNU_API_TOKEN`.
4	`LOGIN_PENDING`	The person is signing in at `loginUrl`.	Run the same command again once they have.

Commands

revnu setup [--website <url>] [-y] [--json] [--wait <seconds>] [--no-login]
revnu setup status [--wait <seconds>]
revnu setup confirm [--keep-found] [--row <id>=<value>]... [--business-name "..."] [--extra "..."]
revnu setup checkout [--open] [--new] [--wait <seconds>]
revnu setup finish
revnu login [--json] [--wait <seconds>]
revnu login --code <url>                    # the browser was on another machine
revnu logout
revnu auth login                            # paste a token instead
revnu auth status                           # which token source is in use, never the token
revnu auth logout
revnu whoami                                # the account and scopes behind the token
revnu mcp                                   # local MCP server over stdio
revnu review list [--status pending|needs_revision] [--limit N]
revnu review get <id>
revnu review approve <id>
revnu review answer <id> --text "..."
revnu review choose <id> --option <value>
revnu review send <id> [--body "..."]
revnu review request-changes <id> --text "..."
revnu review snooze <id> --until <epoch-ms|ISO>
revnu review dismiss <id> [--reason "..."]
revnu agent message "..." [--wait <seconds>] [--client-id <id>] [--queue]
revnu agent poll <requestId>
revnu agent status
revnu agent thread [--limit N]
revnu results [--since <epoch-ms|ISO>]
revnu workflows list
revnu workflows runs <id> [--limit N]
revnu workflows create --json '<body>'      # or --json @body.json
revnu workflows update <id> --json '<body>'
revnu workflows pause <id>
revnu workflows resume <id>
revnu workflows run <id> [--client-id c]    # run it now; the schedule stays
revnu workflows delete <id>
revnu leads list [--status s] [--limit N] [--cursor c] [--workflow-run id]
revnu leads get <id>
revnu leads update <id> [--vertical v] [--archetype a] [--tags a,b] [--clear vertical,archetype,tags]
revnu linkedin person <profile url> [--account name]
revnu blocklist list [--limit N] [--cursor c]
revnu blocklist add <value>... [--reason "..."]
revnu blocklist remove <id>
revnu customers sync --json '<record>'
revnu customers import --json @customers.json [--dry-run]

agent message waits 60 seconds for the reply by default, up to 300 with --wait. A new message stops work Revnu is still doing for this token; pass --queue to hand over another job that starts once the current one is done, and --client-id so a retry never sends twice. See Talk to Your Agent.

The --json body for workflows create and update is the same object the create and update routes take. --tags replaces the whole list; --tags "" empties it and --clear tags removes it.

customers sync sends one record to Sync Existing Customers, and customers import sends a file shaped {"customers": [...]} of up to 5,000 records, one request each, retrying rate limits and server errors. --dry-run checks the records without sending them.

Review history search and the no-account preview run through the API, and review history also through the review_search MCP tool.

Output

The data commands (whoami, review, agent, results, workflows, leads, linkedin, blocklist, customers) and auth status/auth logout print JSON to stdout, so | jq works. login and setup print text, or one JSON object with --json. auth login, help and version print text, and mcp owns stdout for the MCP transport, so never pipe those.

Exit codes for every command: 0 ok, 1 the API said no or the network failed, 2 usage. login and setup add 3 (not signed in, nobody to sign in) and 4 (sign-in still in progress).

Frequently Asked Questions

Can I create a Revnu account from the terminal?

Yes. npx -y @revnu/cli setup opens Revnu's sign-in page, which creates the account for someone new, then walks through the website, the research review, checkout and the first start. A coding agent runs the same thing with --json.

What does exit code 4 mean?

LOGIN_PENDING: the person hasn't finished signing in at loginUrl yet. Show them the link and run the same command again once they have. It is not an error to retry.

Can I see what Revnu would do before signing up?

Yes, without the CLI: POST the website to https://revnu.com/api/v1/preview with no token. See Preview a Plan Without an Account.

Can a coding agent pay for the subscription?

The person pays. The CLI hands over a Stripe Checkout link and they finish it on Stripe's page, so card details never pass through the CLI or the API.

Where is the token stored?

In ~/.config/revnu/config.json with mode 600, or wherever XDG_CONFIG_HOME points. revnu logout deletes the file but doesn't revoke the token. A token from revnu login is listed in Settings → Developers as "Revnu CLI", with the agent's name when an agent ran it. Signing in again saves a new token in the file. The old one stays live, and when that label is still in use the new one gets a number ("Revnu CLI 2"), so revoke the old one in Settings → Developers.

Can I use it in CI?

Yes. Set REVNU_API_TOKEN as a secret and call the commands directly; nothing is interactive when the token comes from the environment. In CI, setup and login exit 3 rather than wait for a sign-in nobody can do.