Skip to content
douyin

Quick start

Run your first douyin command.

# Hot-search billboard in rank order (table at TTY, JSONL piped)
douyin hot

# Top 10 hot videos
douyin hot --tab video -n 10

# Output as JSON
douyin hot -o json

# Just the search links
douyin hot -o url

The --tab flag chooses the billboard: realtime (the default, open from any IP), video, music, or star. The realtime word board returns real data everywhere. The other three tabs are anti-bot-walled from non-China IPs and exit cleanly (exit 3 when the list comes back empty, exit 4 when the server returns a block) rather than faking data.

A video, a user, posts, comments

# One video by URL or bare aweme id
douyin video https://www.douyin.com/video/7106594312292453675

# A profile by sec_uid or URL
douyin user MS4wLjABAAAA...

# A user's public videos
douyin posts MS4wLjABAAAA... -n 50

# Comments under a video
douyin comments 7106594312292453675 -n 100

These call the signed www.douyin.com/aweme/v1/web/* API. They are anti-bot-walled from non-China and datacenter IPs: the signed endpoints return an empty body on an HTTP 200, and the web pages return an __ac JavaScript challenge. The command detects the wall and exits 4 (needs auth) with a hint that the surface needs a residential session. The parsers are correct and return full records from a China IP or a warm browser session.

# The query is variadic, so this is one query of three words
douyin search 美食 教程 -n 20

# Just the result links
douyin search 旅行 -o url

search is walled like video.

Serve over HTTP or MCP

douyin serve                # HTTP, NDJSON; /healthz and /v1/openapi.json
douyin mcp                  # MCP server over stdio

Pipe to jq

douyin hot | jq -r '.word'
douyin hot --tab video -n 5 | jq '{word, hot_value}'
2 min read