# CLI

Citypicked from the terminal. Send review requests, get review links and QR codes, and read feedback and numbers, by hand or in scripts.

Source: https://citypicked.com/en/developers/cli

> The `citypicked` package is not on npm yet. This page describes the CLI as it is built. Until it is published, the [REST API](https://citypicked.com/en/developers/api) and [MCP](https://citypicked.com/en/developers/mcp) do the same.

## Set up

It needs Node.js 20 or newer. Log in once with an API key, or set it as a variable in scripts.

```bash
npx citypicked login

# or, in scripts
export CITYPICKED_API_KEY=cp_live_xxxxxxxx
export CITYPICKED_BASE_URL=https://api.citypicked.com/v1
```

`login` keeps the key in `~/.config/citypicked/config.json` (on Windows in `%APPDATA%\citypicked`), readable only by you.

## Commands

| Command | What it does |
| --- | --- |
| `citypicked login` | Checks a key and saves it, readable only by you |
| `citypicked logout` | Removes the saved key |
| `citypicked whoami` | Shows the account, the key's name and scopes, and whether it can send |
| `citypicked locations` | Lists your locations with id and review link |
| `citypicked link [--location <id>] [--qr <file.png \| file.svg>]` | Shows the review link, or saves its QR code |
| `citypicked send --name <name> (--email <address> \| --phone <number>) --consent` | Sends one review request and asks before it does, unless you pass --yes |
| `citypicked requests [--status <status>] [--since <when>] [--location <id>]` | Lists review requests, newest first |
| `citypicked feedback [--status <status>] [--since <when>] [--location <id>]` | Lists private feedback |
| `citypicked stats [--from <date>] [--to <date>] [--location <id>]` | Shows the numbers for a range of days, by default the last 30 |
| `citypicked webhooks [list] \| add <url> --events <a,b> \| remove <id>` | Lists, adds and removes the webhooks of this key |

Every command takes `--json` (raw JSON on stdout, errors as JSON on stderr), `--base-url <url>` and `--help`. Lists take `--limit`, `--cursor` and `--all`. `--since` takes `7d`, `12h`, `2w`, a date or a timestamp.

## Examples

```bash
citypicked send --name "Emma Clark" --email emma@example.com --consent

# in a script, without asking
citypicked send --name "$NAME" --email "$EMAIL" --consent --yes --json

citypicked requests --status rated --since 1d --json | jq '.data[].id'
citypicked link --qr counter.png
citypicked webhooks add https://example.com/hooks/citypicked --events feedback.created,request.rated --json | jq -r .secret
```

Without a terminal, `send` and `webhooks remove` need `--yes`; neither acts silently otherwise. `--consent` confirms the customer agreed to get messages.

## Exit codes

| Code | Meaning |
| --- | --- |
| 0 | Done |
| 1 | Unexpected error |
| 2 | Wrong usage, or sending not confirmed |
| 3 | No API key, or the key was refused |
| 4 | Not allowed (key without send, plan without API sending) |
| 5 | Not found |
| 6 | The API refused the input |
| 7 | Rate limited |
| 8 | Plan wall, the trial is over or the plan has no access |
| 9 | Account closed |
| 10 | Server or network error |
| 11 | Nothing was sent (duplicate, opted out, no credits) |
| 12 | Canceled at the prompt |