# TokConnect CLI and Python client

The TokConnect CLI turns every route in this reference into a command: `tokconnect products top --keyword "lip oil"`. It prints the API's JSON, so it works in scripts, in `jq` pipelines and in an AI agent's shell. The Python package adds a client with one method per route.

The REST API is on every paid plan. [Paid plans](https://tokconnect.com/pricing/) from $34.99 a month.

[Get an API key](https://app.tokconnect.com/api-key)[npm](https://www.npmjs.com/package/tokconnect)[PyPI](https://pypi.org/project/tokconnect/)

- **npm:** `npx tokconnect` (Node.js 18+)
- **PyPI:** `pip install tokconnect` (Python 3.9+)

## Install and sign in

Use either package. Both have the same commands and no other dependencies.

Install:

```
npx tokconnect login
# or
pip install tokconnect && tokconnect login
```

`tokconnect login` saves your key to `~/.config/tokconnect/config.json`, readable only by you. You can also set `TOKCONNECT_API_KEY` or pass `--key`. Your key is on the [API key page](https://app.tokconnect.com/api-key).

## Commands

Each route `/v1/<group>/<words>` is the command `tokconnect <group> <words>`. Ids and TikTok links in the path become arguments, and query parameters become options with the same names.

Examples:

```
tokconnect products top --keyword "lip oil" --region US --limit 5
tokconnect videos transcript https://www.tiktok.com/@creator/video/7691522530129022221
tokconnect searches list --keyword "glass skin"
tokconnect products top --keyword "phone case" --all --max-pages 5
```

- `tokconnect commands` lists every command (`--json` for agents).
- `tokconnect describe products top` shows the options, credits and an example.
- `tokconnect call GET /v1/...` reaches any route by path, and `tokconnect sync` picks up new routes without updating the CLI.
- `--all` follows `next_cursor` and merges the pages; each page costs credits.

## Output and exit codes

The output is the API response: `data`, `next_cursor` and `meta`. It is pretty-printed in a terminal and compact when piped. Errors go to stderr with the API's error JSON. On 429 and 503 the CLI waits the `Retry-After` seconds and retries twice; see [Errors](https://tokconnect.com/docs/api/errors/).

Exit codes: `0` ok, `1` API or network error, `2` bad usage or request, `3` key missing or not allowed, `4` out of credits, `5` rate limited.

## Python client

Python:

```
from tokconnect import Client, TokConnectError

tc = Client()  # TOKCONNECT_API_KEY, the saved key, or Client(api_key="...")
best = tc.products.top(keyword="lip oil", region="US", limit=5)
for p in best["data"]["items"]:
    print(p["product_title"], p["revenue"])

tc.creators.shop_sales("tokconnect", start="2026-10-01")
tc.run("searches list", keyword="glass skin")
```

Each method returns the response JSON. Errors raise `TokConnectError` with `status`, `type` and `body`.

The REST API is on every paid plan. [Paid plans](https://tokconnect.com/pricing/) from $34.99 a month.

[Get an API key](https://app.tokconnect.com/api-key)[Quickstart](https://tokconnect.com/docs/api/quickstart/)[MCP](https://tokconnect.com/docs/api/mcp/)

---

Last updated 2 Nov 2026. Source: https://tokconnect.com/docs/api/cli/  
All TokConnect API docs as one Markdown file: https://tokconnect.com/docs/api/llms-full.txt