Metadata-Version: 2.4
Name: selltostate-cli
Version: 0.1.0
Summary: selltostate: official CLI for the Sell to State government-contracts data API (REST/MCP parity).
License-Expression: MIT
Project-URL: Homepage, https://www.selltostate.com/cli/
Project-URL: Source, https://github.com/getbeton/selltostate-cli
Keywords: selltostate,government,tenders,procurement,cli
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# `selltostate-cli` — `selltostate`

Official command-line client for the **Sell to State** government-contracts data API
(`app.selltostate.com`). Python port of the npm package
[`@selltostate/cli`](https://www.npmjs.com/package/@selltostate/cli): the same commands,
flags, output and exit codes. Standard library only, Python 3.9+.

```bash
pipx install selltostate-cli      # or: pip install selltostate-cli / uv tool install selltostate-cli
selltostate auth login            # prompts for the key, checks it with /whoami, saves it
selltostate search "IT consulting" --country singapore --year-min 2026 --format json
```

Get a key at `https://app.selltostate.com/dashboard` (Settings -> API keys).

## Auth and configuration

The CLI sends a dashboard API key as the `x-api-key` header. Resolution order:

1. `--api-key` / `--api-url` flags
2. `STS_API_KEY` / `STS_API_URL` environment variables
3. `~/.config/selltostate/config.json` (written by `auth login`, mode `0600`; honours `XDG_CONFIG_HOME`)
4. Default API URL `https://app.selltostate.com`

The npm and the Python CLI share this config file.

## Commands

| Command | Endpoint |
| --- | --- |
| `whoami` | `GET /api/v1/whoami` |
| `search <q> [filters]` | `GET /api/v1/search` |
| `awards [filters]` | `GET /api/v1/awards` |
| `get buyer\|supplier\|tender\|sector <id>` | `GET /api/v1/{buyers\|suppliers\|tenders\|sectors}/<id>` (tender: `award_id`) |
| `sectors`, `suppliers [--limit]`, `buyers [--limit]` | `GET /api/v1/{sectors\|suppliers\|buyers}` |
| `lists ls\|create\|show\|add\|rm\|rename\|delete` | `/api/v1/lists*` |
| `saved-searches ls\|save\|show\|rename\|delete` | `/api/v1/saved-searches*` |
| `export [filters] [-o file]` | `GET /api/v1/awards.csv` |
| `price` | `GET /api/v1/price` (no auth) |
| `pay [--token --customer]` | `POST /api/v1/pay` |

`--format table|json|csv` (default `table`; `--json` = `--format json`). Run
`selltostate <command> --help` for the flags of one command.

## Exit codes

`0` success · `1` error · `2` unauthorized (401) · `3` payment required (402) · `4` rate limited (429) · `64` usage error

## Development

This package lives in the `data-atlas` monorepo next to `packages/cli`. Keep both in lockstep.

```bash
python -m unittest discover -s tests   # no network; compares --help with packages/cli/dist when it is built
uv build                               # dist/selltostate_cli-<version>-py3-none-any.whl
```
