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.
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:
--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.
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
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.