# Command line

One npx command away: search companies, read a market, read a watch, and page through any of them from a shell script.

Zero runtime dependencies, one binary, Node 22.12 or newer. Browser login is the default.

```bash
npx -y prospex login
npx -y prospex usage
npx -y prospex companies search --q "precision machining" --canton VD
```

The command prints a fallback URL and code, opens the browser when possible, and stores short-lived OAuth credentials after approval. Every data command prints the API payload on stdout unchanged, so every example on these pages is also a CLI example.

## Commands

| Command | What it does | Calls | Spends |
| --- | --- | --- | --- |
| login | Authenticate in the browser, or store an API key for automation. | local | nothing |
| logout | Forget the stored key for a profile. | local | nothing |
| whoami | Which key is in use, by its 12-character prefix, and what it may do. | GET /api/v1/usage | nothing |
| usage | Rows and requests spent today, and what is left. Run this before --all. | GET /api/v1/usage | nothing |
| companies search | Search the Swiss company register. | GET /api/v1/companies | one per record |
| companies get | One company, with its few most recent events. | GET /api/v1/companies/:id | one per record |
| companies signals | Every visible event on one company, newest first. | GET /api/v1/companies/:id/signals | one per record |
| markets list | Your markets, with their state and their Core count. Costs no rows. | GET /api/v1/markets | nothing |
| markets get | One market: its definition, the queries the build ran, its state. | GET /api/v1/markets/:id | nothing |
| markets rows | The companies in a market, with the reasons they are there. | GET /api/v1/markets/:id/companies | one per record |
| watches list | Your active watches. Costs no rows. | GET /api/v1/watches | nothing |
| watches get | One watch: what it listens for, and how many companies it holds. | GET /api/v1/watches/:id | nothing |
| watches signals | What changed on a watch, newest first. | GET /api/v1/watches/:id/signals | one per record |
| projects list | Your Prospect projects. Needs a pilot key. | GET /api/v1/prospect/projects | nothing |
| projects get | One Prospect project. | GET /api/v1/prospect/projects/:id | nothing |
| prospects list | The prospects in a project, with their fit, research and outreach. | GET /api/v1/prospect/projects/:project/prospects | one per record |
| prospects get | One prospect, with every current revision. | GET /api/v1/prospect/projects/:project/prospects/:id | nothing |
| prospects add | Add one company to a Prospect project. | POST /api/v1/prospect/projects/:project/prospects | nothing |
| prospects decide | Pin, exclude, restore, dismiss or set the language on one prospect. | POST /api/v1/prospect/projects/:project/prospects/:id/decisions | nothing |
| prospects research | Request a fresh research cycle for one prospect. | POST /api/v1/prospect/projects/:project/prospects/:id/research | nothing |
| prospects approve | Approve the exact outreach revision that was reviewed. | POST /api/v1/prospect/projects/:project/prospects/:id/approvals | nothing |
| cycles start | Start a project cycle, optionally for named prospects. | POST /api/v1/prospect/projects/:project/cycles | nothing |
| cycles get | Read one project cycle and its current state. | GET /api/v1/prospect/projects/:project/cycles/:id | nothing |
| jobs list | List external stage jobs in a Prospect project. | GET /api/v1/prospect/projects/:project/stage-jobs | nothing |
| jobs get | Read one external stage job, including its immutable input. | GET /api/v1/prospect/projects/:project/stage-jobs/:id | nothing |
| jobs claim | Claim one external stage job for this credential. | POST /api/v1/prospect/projects/:project/stage-jobs/:id/claims | nothing |
| jobs submit | Submit a stage result against the job input snapshot. | POST /api/v1/prospect/projects/:project/stage-jobs/:id/results | nothing |
| jobs fail | Mark a claimed stage job failed and say why. | POST /api/v1/prospect/projects/:project/stage-jobs/:id/failures | nothing |
| jobs cancel | Cancel an external stage job. | POST /api/v1/prospect/projects/:project/stage-jobs/:id/cancellations | nothing |
| jobs retry | Open a fresh job from the same immutable input. | POST /api/v1/prospect/projects/:project/stage-jobs/:id/retries | nothing |
| skill install | Write the agent skill into this project or your home directory. | local | nothing |
| mcp add | Authenticate and configure every detected supported MCP client. | local | nothing |
| mcp serve | Run the local newline-delimited stdio bridge. | local | nothing |
| spec | This command table, as JSON. What commands.json is generated from. | local | nothing |
| raw | Call any API path. For a route the CLI has no command for yet. | local | nothing |

`prospex spec --json` prints this table as JSON, with every flag and its accepted values. It is what this page is generated from.

## Credentials

`prospex login` stores an OAuth access token and rotating refresh token in a version 2 credentials file. The CLI refreshes before expiry with an inter-process lock and an atomic `0600` write.

API keys remain available for CI and existing integrations. Their resolution order is:

```plaintext
--key  >  PROSPEX_API_KEY  >  --credentials  >  PROSPEX_CREDENTIALS
       >  ${XDG_CONFIG_HOME:-~/.config}/prospex/credentials.json
```

In CI, set `PROSPEX_API_KEY`. You can also run `prospex login --key pxk_…`; entering a key as a command flag may save it in shell history. The CLI warns when a POSIX credentials file has loose permissions. Protect the credentials file with the matching Windows account controls on Windows.

`prospex whoami` reports whether the profile uses OAuth or an API key and never prints the credential. Use `--profile` to keep more than one account or environment.

A base URL resolves `--base-url` > `PROSPEX_BASE_URL` > the profile > `https://prospex.ch`.

## Paging

`--all` follows `next_cursor` to the end. It stops at `--max-pages` (default 10) and at half of whatever remains of the day's row budget, and the payload it prints keeps `has_more` and a live `next_cursor`, so a walk that stopped early can be resumed.

```bash
prospex usage
prospex markets rows 41 --band strong,good --all --max-pages 4 --format csv > core.csv
```

On a 429 mid-walk, `--all` stops and exits 9. It never sleeps: the reset is local midnight, so `Retry-After` can be tens of thousands of seconds.

Maximum page size 100.

## Output

`--format` takes `json`, `compact`, `table`, `ndjson`, `csv`. `json` is the default everywhere, in a terminal and in a pipe alike, so the same command always produces the same bytes.

CSV and the table are rendered from the JSON on your machine. Rate-limit state is one line on stderr, silenced by `--quiet`; `prospex usage` is the machine-readable form.

## Exit codes

| Code | Meaning |
| --- | --- |
| 0 | Worked. |
| 1 | An unexpected failure. Read stderr. |
| 2 | The command line was wrong. Nothing was sent. |
| 3 | No usable credential, or authentication was rejected. |
| 4 | The key does not hold the scope this command needs. |
| 5 | The subscription is not active. Retrying cannot fix it. |
| 6 | No such object. |
| 7 | A cycle is already running on that project. |
| 8 | Understood and refused on its content. |
| 9 | Out of allowance: requests, or rows. |
| 10 | The surface is switched off server-side. |
| 11 | The request never reached Prospex. |

Errors print as one JSON object on stderr carrying `request_id`, so a support message is one copy-paste.

## Mutations and raw requests

```bash
prospex prospects decide project_7 prospect_42 --decision pin \
  --idempotency-key review-42
prospex raw GET /companies/12345/signals
```

Prospect mutations need a pilot key with the scope shown in the command table. Reuse the same `--idempotency-key` when you retry one. A fresh key on a retry is a second mutation.

`prospex raw <METHOD> <path>` remains available for direct API calls.