Skip to content
tt

v0.1.0

The first public release of tt: the full read surface across both planes, the discovery walk, and the signing packages.

The first public release. tt is a single pure-Go binary that reads public TikTok data and prints clean, pipeable records. It needs no API key and no login. It reads the same public web surface a logged-out browser sees: the server rendered universal-data blob each page ships, and the www.tiktok.com/api/* endpoints the page's own JavaScript calls, signed the way the web client signs them. Every request is paced, retried on transient failures, and sent with an honest User-Agent.

What you get

  • Read one thing. tt video and tt user pull a single video or profile record straight from the page's own JSON, with the author, sound, hashtags, dimensions, playable urls, and every counter.
  • Page a feed. tt posts walks a user's videos by handle or secUid, tt comments and tt replies read a video's discussion, and tt trending reads the logged-out recommend feed.
  • Search. tt search returns mixed video and user hits; tt users narrows to accounts.
  • Hashtags and sounds. tt hashtag and tt sound return the header record, or the videos under it with --videos.
  • Discover. tt discover walks the public graph outward from seeds and ranks the hottest users, videos, hashtags, and sounds it reaches.
  • See the raw page. tt raw prints a page's whole universal-data blob as pretty JSON, the source every SSR command reads from.

Records come out as table, JSON, JSONL, CSV, TSV, url, or raw. --fields picks and orders columns, --template runs a Go template per record, and -o url gives a clean link stream. Every record carries its own url.

Two planes, two reliabilities

TikTok serves data through two channels that fail differently, and tt is built around the difference.

The SSR plane reads the JSON a logged-out page already ships, with no signing. tt video and tt raw ride it and answer from anywhere.

The API plane calls www.tiktok.com/api/* for listings, comments, and search. Those calls carry an X-Bogus signature and an msToken and sit behind a firewall that scores the caller's IP. From a residential session they answer; from a datacenter IP they are often gated. When the firewall gates a call, tt exits 4 with a clear message instead of pretending it found nothing. See troubleshooting for the full surface map.

The discovery walk

tt discover is the one command that crosses both planes in a single run. Seed it from a user, hashtag, sound, video, search phrase, or the trending feed, and it walks the graph outward, scoring every node by how hot it is: plays and velocity for videos, followers for users, views for hashtags, uses for sounds.

The walk is best-first, so a shallow run still surfaces the strongest nodes first, and it is bounded by depth, fanout, and node and request budgets. --top and --min-score rank the output, --kind filters what it emits, and --edges writes the traversed graph as JSONL alongside the nodes. From a gated IP the walk reaches what the page blobs give and records every list edge it could not page, so it stays honest about what it saw. See the discovery guide.

Signing packages you can import

The pieces that make the API plane callable live in their own packages, so you can sign requests from your own program without the rest of the tool:

import "github.com/tamnd/tiktok-cli/pkg/ttsign"

pkg/ttsign builds an msToken and the X-Bogus and a_bogus signatures the web client attaches to every API call. pkg/tthtml pulls a named <script> JSON blob out of a page and tells a real record apart from a firewall challenge.

Install

go install github.com/tamnd/tiktok-cli/cmd/tt@latest

Or grab a prebuilt binary from the release, or run the container image:

docker run --rm ghcr.io/tamnd/tiktok:0.1.0 --help

Every tagged version builds archives for Linux, macOS, Windows, and FreeBSD, Linux packages (deb, rpm, apk), a multi-arch GHCR image, checksums, SBOMs, and a cosign signature. The binary is pure Go, so there is nothing to install alongside it.

4 min read