> ## Documentation Index
> Fetch the complete documentation index at: https://docs.populardemand.market/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> A command-line client for agents with their own computer.

Use it when your agent runs commands on its own computer and schedules jobs, as Grok Bot and Muse do. It is one Node 20+ file with no dependencies, served by Popular Demand, and it calls the same REST API as the 9 MCP tools.

> [!NOTE]
>
> Version 0.2.0 reads and changes the buyer's Requests. No command pays or buys. Closing a Request asks the buyer by email: with your agent's token, `close` pauses the Request and Popular Demand emails the buyer a link to close it, keep it paused or resume it.

## Install

```bash theme={null}
export POPULAR_DEMAND_URL='https://populardemand.market'
curl -fsSLo pd.mjs https://populardemand.market/cli/popular-demand.mjs
curl -fsSL https://populardemand.market/cli/popular-demand.mjs.sha256
shasum -a 256 pd.mjs
node pd.mjs login --host-name "Your agent"
```

Check the file against the published SHA-256.

## Sign in

Your agent's computer cannot show the buyer a browser, so the buyer carries a code back:

1. `node pd.mjs login` prints a sign-in link. Your agent sends it to the buyer.
2. The buyer signs in on their own device and approves. The page shows one code starting with `pdc_`.
3. The buyer gives the code to your agent, which runs `node pd.mjs login --code pdc_…`.

Tokens are stored with mode 0600 under `$XDG_CONFIG_HOME/popular-demand/` and refresh automatically.

## Commands

| Command | Does |
| - | - |
| `login [--code C] [--host-name H]` | Sign in (above). |
| `logout` | Delete the stored credentials. The buyer revokes the CLI in their account to end its access. |
| `whoami` | Show the signed-in client. |
| `doctor` | Check Node, both hosts and the credentials. |
| `list [--status open\|closed\|all]` | List the buyer's Requests, with what needs attention. |
| `get ID` | Read one Request and its open questions. |
| `offers ID [--offer OFFER_ID]` | Read a Request's Offers, with what to tell the buyer and their Offer link. |
| `save --file F` | Save a Request the buyer agreed to. `F` is the `request` JSON (`-` reads stdin). |
| `update ID --version N --file F` | Change a Request. `F` is the `changes` JSON. |
| `close ID --version N --reason R` | Pause the Request and email the buyer a link to close it. |
| `answer ID QUESTION_ID (--choice X \| --text X \| --unknown)` | Answer `still_want` (`yes` or `pause`) or a seller question. |
| `respond ID OFFER_ID --offer-version N --version N (--fits \| --does-not-fit) [--reason CODE] [--note T]` | Say whether the Offer version the buyer saw fits. It neither buys nor reserves anything. |
| `notify [ID] [--offer-alerts on\|off] [--check-frequency F] [--check-channels C] [--agent-poll HOURS\|off] [--agent-email on\|off]` | Change notification settings. Without an ID, only the account-wide frequency and channels. |
| `check [--all]` | For scheduled jobs: report what is new for the buyer. |
| `retry` | Send the last unfinished change again, with the same Idempotency-Key. |

`requests list` and `requests get ID` still work in 0.2.0 and are removed in the next version. `--json` prints the API's own JSON. `node pd.mjs help` lists every command.

Each `save`, `update`, `close`, `answer`, `respond` and `notify` gets a fresh random Idempotency-Key, kept in its own `pending-op-<key>.json` beside the credentials until the API answers. If the network fails, run `retry`: the API replays the first answer instead of saving twice. A new `login` drops unfinished changes, because they may belong to another account.

## Scheduling

Run `node pd.mjs check --json` every 6 hours, starting at a random minute, and act when it exits 10. It reads each open Request's `needs_attention` and follows only what is flagged: new Offers, Offers ending within 48 hours, `still_want`, seller questions, details needed and Requests ending within 7 days. Each item is reported once (`check-state.json`), and each comes with a `next` command. Where the buyer chooses, `next` has `CHOICE` or `VALUE` to fill in from `choices`; text mode prints one command per choice, with seller text quoted for the shell.

```json theme={null}
{"new":[{"kind":"new_offer","request_id":"…","title":"…","offer_id":"…","offer_version":2,
  "ends_at":"…","tell_person":"…","offer_link":"…","next":"pd offers … --offer …"}],
 "open_requests":3,"complete":true,"previous_run":"…","cli_version":"0.2.0"}
```

The buyer still gets their own Offer and `still_want` emails, whatever your agent does.

| Exit | Meaning |
| - | - |
| 0 | Done; for `check`, nothing new |
| 2 | Usage error |
| 3 | Refused by the API |
| 4 | Not signed in, or the grant was revoked |
| 5 | Network blocked or unreachable |
| 6 | Rate limited |
| 10 | `check` found something new for the buyer |

A failed or partial scan exits with its error, never 0, and leaves `check-state.json` as it was.

The CLI needs two hosts: `populardemand.market` and `mcp.populardemand.market`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.