Metadata-Version: 2.4
Name: tokconnect
Version: 0.1.0
Summary: TokConnect CLI and Python client: TikTok Shop sales, TikTok search demand, videos, comments, transcripts, creators and more from the TokConnect API.
Author-email: Tokconnect LLC <dj@tokconnect.com>
License-Expression: MIT
Project-URL: Homepage, https://tokconnect.com/
Project-URL: Documentation, https://tokconnect.com/docs/api/
Project-URL: API spec, https://tokconnect.com/openapi.json
Keywords: tiktok,tiktok-api,tiktok-shop,tiktok-data,cli,mcp,ai-agents,tokconnect
Classifier: Programming Language :: Python :: 3
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# TokConnect CLI

TikTok data in your terminal, or in your AI agent's shell: TikTok Shop sales estimates in 17 markets, what people search on TikTok, and public videos, comments, transcripts, creators, hashtags, sounds, LIVEs and ads. It wraps the [TokConnect REST API](https://tokconnect.com/docs/api/): one command per API route, 137 in all.

```bash
pip install tokconnect                    # or: pipx install tokconnect
tokconnect login                          # paste your API key once
tokconnect products top --keyword "lip oil" --region US --limit 5
```

Needs Python 3.9 or newer. No other dependencies. Also on npm: `npx tokconnect`.

## In Python

```python
from tokconnect import Client, TokConnectError

tc = Client()  # key from TOKCONNECT_API_KEY or `tokconnect login`; 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.videos.transcript("https://www.tiktok.com/@creator/video/7691522530129022221")
tc.creators.shop_sales("tokconnect", start="2026-10-01")   # two-word commands use underscores
tc.run("searches list", keyword="glass skin")              # or the CLI command as a string
tc.request("GET", "/v1/markets")                            # any route by path
```

Each method returns the API's JSON (`data`, `next_cursor`, `meta`). Errors raise `TokConnectError` with `.status`, `.type` and `.body`. A 429 or 503 is retried twice, after the `Retry-After` wait.

## API key

The REST API is on every paid TokConnect plan. Get a key at [app.tokconnect.com/api-key](https://app.tokconnect.com/api-key), then either:

- run `tokconnect login` (saved to `~/.config/tokconnect/config.json`, readable only by you),
- set `TOKCONNECT_API_KEY`, or
- pass `--key` on any command.

Most commands cost 1 credit. Failed calls are free.

## Examples

```bash
# What sells on TikTok Shop
tokconnect products top --category Skincare --launched-within-days 30
tokconnect shops top --region GB --limit 10
tokconnect products sales 1729384756 --start 2026-10-01 --end 2026-10-31

# What people search on TikTok
tokconnect searches list --keyword "glass skin"
tokconnect searches trending

# Videos, creators and comments (ids or full TikTok links)
tokconnect videos transcript https://www.tiktok.com/@creator/video/7691522530129022221
tokconnect videos comments 7691522530129022221 --limit 50
tokconnect creators get tokconnect

# Every page of a list, merged (each page costs credits)
tokconnect products top --keyword "phone case" --all --max-pages 5
```

## Find your way around

```bash
tokconnect --help                     # usage and the command groups
tokconnect commands                   # every command
tokconnect commands products --json   # machine-readable, for agents
tokconnect describe products top      # options, credits and an example
tokconnect call GET /v1/products/top --keyword mug   # any route by path
tokconnect sync                       # pick up new API routes without updating the CLI
```

Options follow the API's parameter names. `--max-rows` and `--max_rows` both work. List options can be repeated or comma-separated.

## Output and exit codes

The output is the API's JSON response: `data`, `next_cursor` and `meta` (credits charged and left). It is pretty-printed in a terminal and compact when piped. Use `--pretty` or `--compact` to choose. Pipe it into `jq`:

```bash
tokconnect products top --keyword "lip oil" | jq '.data.items[] | {product_title, revenue}'
```

Errors go to stderr as the API's error JSON. Exit codes:

| Code | Meaning |
|---|---|
| 0 | success |
| 1 | API or network error |
| 2 | bad usage or a bad request |
| 3 | no API key, or the key is not allowed |
| 4 | out of credits |
| 5 | rate limited |

On a 429 or 503 the CLI waits the `Retry-After` seconds and retries up to twice. Use `--no-retry` to turn this off.

## For AI agents

- **One-line call:** `tokconnect <group> <command> ... --compact` gives your agent TikTok data.
- **Discover commands:** `tokconnect commands --json` and `tokconnect describe <group> <command> --json`.
- **Prefer MCP?** TokConnect also runs an MCP server at `https://mcp.tokconnect.com/mcp`. Setup: [tokconnect.com/connect](https://tokconnect.com/connect/).
- **Agent guide:** [tokconnect.com/llms.txt](https://tokconnect.com/llms.txt).

## Links

- [API docs](https://tokconnect.com/docs/api/)
- [OpenAPI spec](https://tokconnect.com/openapi.json)
- [Pricing](https://tokconnect.com/pricing/)
- Support: dj@tokconnect.com

TokConnect is an independent service, not affiliated with TikTok.
