TokConnect CLI and Python client

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.

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.

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.

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.

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

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.