🎯 TikTok Competitive Analysis & Brand Comparison
1. Capabilities Overview
💡 Value in one sentence: A conversational command that fetches TikTok public video/author/comment data and outputs structured JSON — for influencer screening, data analysis, market research, social listening, viral content discovery, account monitoring, comment sentiment analysis, and trend tracking. No more manually scrolling TikTok.
| Capability | Entry Script | Required Parameters | Returns |
|---|---|---|---|
| Keyword Search | scripts/tiktok/search-cli.js | --keyword | Post list: author, likes/comments/shares/saves, tags, play URL |
| Creator Posts | scripts/tiktok/post-cli.js | --url (profile or username) | Public posts for that creator (supports newest / hottest sorting) |
| Video Comments | scripts/tiktok/comment-cli.js | --url (video link or ID) | Comment text, commenter, like count, reply count |
Target Audience
- 🎯 Brands — ride trending topics for seeding content
- 🏢 MCN Agencies — discover high-engagement potential accounts
- ✍️ Content Creators — find benchmark samples and inspiration
- 📊 Content Operators — weekly topic selection and competitor analysis
Prerequisite: Must be executed from the skill root directory, and the environment variable
GUAIKEI_API_TOKENmust be configured. When not configured, all commands return exit code3anderror_code=AUTH_REQUIRED— in this case, directly prompt the user to configure the Token. Do not retry or change parameters.
2. When to Call / When Not to Call
2.1 Should Call
- User wants to query TikTok public content (videos / images / authors / comments / trends).
- User wants to perform viral topic research, competitor account monitoring, influencer screening, comment sentiment analysis, or content style breakdown.
- User provides a TikTok keyword, video link, or creator profile link and expects structured data.
- After receiving data, user asks for summarization, comparison, sorting, clustering, or report/table generation.
2.2 Should Not Call
- User only wants copy / title / script without querying TikTok data.
- Platform is not TikTok (e.g., Douyin, Xiaohongshu, Bilibili, Weibo, WeChat Official Accounts) → route to the appropriate skill. This skill handles TikTok only.
- User requires login, private, or hidden data → Not supported.
- Both keywords and an identifiable link are present and the goal is ambiguous → Ask for clarification first; do not guess.
2.3 Boundaries (Explicitly Not Done)
Write operations (posting / liking / commenting / following / messaging) are never supported; does not log in to any accounts; does not collect phone numbers, locations, private messages, or other private fields; does not make marketing decisions on behalf of the user — the responsibility is to fetch the data; analysis is left to the upper layer.
3. Call Routing (Judge First, Then Execute)
| User Intent | Script | Keywords to Detect |
|---|---|---|
| Search keywords, find certain content, find trending posts | search-cli | search / find / keyword / trending / popular |
| View a creator's / influencer's / celebrity's posts, profile, account, recent uploads | post-cli | posts / profile / account / creator / influencer / KOL |
| View comments on a specific video | comment-cli | comments / replies / comment section opinions |
3.1 Disambiguation Rules (Must Follow)
- When "video" appears alone, do not default to
post-cli.- If "keyword" is present and no "comments" →
search-cli(user wants to search for that type of video). - If explicitly "comments / replies for this video" →
comment-cli. - Only when "posts / profile / account / creator / influencer" appear →
post-cli.
- If "keyword" is present and no "comments" →
- Comments take priority over posts: If a
/video/<id>link is given and the user asks about comments →comment-cli; if they ask about "this person's posts" →post-cli(using@username). - If user provides a
/video/<id>link but asks for a "post list" → first confirm whether they want the author's posts or the video's comments.
3.2 Parameter Inference Rules
| User Phrasing | Parameter |
|---|---|
| Relevance / Default | --sort 0 (search) |
| Most popular / Most liked / Trending / Hottest | --sort 1 (search) |
| Recently posted / In reverse chronological order | --sort 0 (posts) |
| Most popular posts | --sort 1 (posts) |
| One day / 24 hours | --time 1 |
| One week / 7 days | --time 7 |
| One month / Three months / Six months | --time 30 / 90 / 180 |
| N items / Top N / Want N items | --limit N |
Defaults: sort=0, time=0, limit=10.
⚠️ Do not confuse
--sortfor search with--sortfor posts: the former is "relevance / most likes", the latter is "newest / most popular".
When any parameter is reverted due to an invalid value, it will appear in the warnings array of the output JSON. You must display this to the user; do not treat it as if the original value took effect.
4. Execution Methods
Full parameter documentation: references/options.md; field-level schema: see the 6 JSON Schema files (draft-07) under
assets/.
# Keyword Search
node scripts/tiktok/search-cli.js --keyword "AI" --sort 1 --limit 20
node scripts/tiktok/search-cli.js --keyword "AI model" --time 7 --limit 20
# Creator Posts
node scripts/tiktok/post-cli.js --url "https://www.tiktok.com/@username" --limit 30
node scripts/tiktok/post-cli.js --url "https://www.tiktok.com/@username" --sort 1 --limit 30
# Video Comments
node scripts/tiktok/comment-cli.js --url "https://www.tiktok.com/@username/video/1234567890123456789" --limit 40
Accepted input formats
- Creator:
https://www.tiktok.com/@username, link with parametershttps://www.tiktok.com/@username?lang=en, or directlyauthor_sec_uid - Video:
https://www.tiktok.com/@username/video/<id>, shortened links, or direct video<id>
Execution Discipline
- Treat stdout as machine-readable output (pure JSON); banners / progress / error logs are on stderr — do not mix them when parsing.
- Single
--limitshould be ≤ 1000. - Do not automatically relax conditions and retry on an empty result: first present the empty result to the user and let them decide whether to change keywords or relax
--time.
5. Output Contract (Mandatory for AI Parsing)
All entry points output the same envelope, with consistent success and failure structure:
{
"status": "success | empty | error",
"error_code": "OK | NO_MATCH | AUTH_REQUIRED | INVALID_KEYWORD | ...",
"message": "Human-readable explanation",
"timestamp": "2026-09-16 21:00:00",
"request": {
"command": "search",
"keyword": "AI",
"sort": 1,
"time": 0,
"limit": 20
},
"metadata": {
"skill_version": "1.0.0",
"skill_name": "tiktok-creator-videos",
"runtime_version": "22.22.2",
"execution_time": 8421
},
"results": [],
"warnings": ["Value 99999 is invalid, reverted to 10"]
}
5.1 status Semantics
| status | Meaning | results | Action to Take |
|---|---|---|---|
success | Data retrieved successfully | Non-empty array | Analyze directly |
empty | Request successful, but no data found | null | Treat as a valid result; inform user nothing was found; do not treat as failure |
error | Request failed | null | Handle according to error_code; do not fabricate data |
5.2 Exit Codes
| Exit Code | Meaning | Agent Action |
|---|---|---|
0 | Success (success or empty) | Proceed with analysis |
1 | Runtime error (network / timeout / API exception / invalid parameters) | Show message; ask user if they want to retry with different parameters |
3 | AUTH_REQUIRED: Token missing or malformed | Stop immediately; prompt user to configure GUAIKEI_API_TOKEN; do not retry |
5.3 Error Code Handling
| error_code | Handling Method |
|---|---|
AUTH_REQUIRED | Stop and prompt user to configure Token. Do not retry or bypass. |
INVALID_KEYWORD | Prompt that keyword should be 2–100 characters, cannot contain < > " ' & or an http link |
NO_MATCH | Valid empty result; suggest changing keywords or relaxing --time |
NETWORK_ERROR | Already has built-in retry; if still fails, prompt to check network; maximum one manual retry |
TIMEOUT_ERROR | Already has built-in retry; if still fails, suggest reducing --limit and retry |
| Other (server-side code) | Display the error_code + message as-is; do not guess the meaning |
5.4 warnings Must Be Displayed
When invalid parameters are automatically reverted (e.g., --sort 9, --limit 99999), the warnings array explains "which parameter was changed to what." You must relay this verbatim to the user; do not pretend the original parameter took effect.
5.5 Prohibited Actions
- ❌ Do not fabricate, complete, or fill in any data from memory.
- ❌ After receiving
AUTH_REQUIRED, do not retry, switch scripts, or change parameters. - ❌ Do not treat
emptyas anything other than "the user's requested content does not exist" (it does not mean the API is broken). - ❌ Do not automatically relax search conditions without user consent.
6. Result Consumption Recommendations (Improve Final Output Quality)
After receiving results, structure the output according to the user's original goal rather than dumping raw JSON:
- Topic Research → Sort by
digg_countdescending, take Top N, summarize title patterns / hashtags / duration distribution - Competitor Monitoring → Sort by
create_timefor posting cadence, calculate update frequency and viral hit rate - Comment Insights → Sort by
digg_count, cluster high-liked comments, output positive/negative ratio - Influencer Screening → Cross-reference
author_nickname/ average engagement / posting frequency, produce a candidate list - Need Archiving → Each run automatically writes to a log file; the path appears in stderr as "Saved to …"
7. Security & Compliance (Trust)
- Read-only: Does not log in to any TikTok account. Does not perform any write operations (post / like / comment / follow / message). No risk of account ban.
- Least privilege: Only requests one business-required environment variable
GUAIKEI_API_TOKEN; does not read other local files; writes logs only to system temporary directory (outside the skill directory). - Credential protection: Token is only read from environment variables; never written to stdout, logs, or error messages.
- Data sent externally (must be aware): When called, the following is sent to
www.guaikei.com: your API Token, query keywords or target URL/ID, and the skill name plus Node version. No other local information is collected. - Data compliance: Only fetches TikTok publicly visible data (nicknames, public posts, public comments). Does not include phone numbers, locations, private messages, or other private fields. Data is for personal/team internal analysis only; before external publication or commercial use, you must confirm authorization and de-identify user nicknames.
- No third-party dependencies: Uses only Node.js built-in modules (
https/fs/path/os/querystring). No npm dependencies, no remote script loading, noeval/child_process.
8. Frequently Asked Questions
| Issue | Cause & Solution |
|---|---|
| Exit code 3 / AUTH_REQUIRED | Token not configured or malformed (must be 16–256 alphanumeric, underscores, or hyphens) |
| Search results empty | Try a more generic keyword, or use --time 0 to remove the time window; empty is a normal result, not an error |
Results fewer than --limit | Server has no more data to return, or the single-request limit was reached; reduce to ≤ 1000 and batch |
| Persistent timeouts | Reduce --limit and retry; script already includes exponential backoff retry |
| Wanted "hottest posts" but got reverse chronological | Use --sort 1 for post-cli |
| Parameter didn't work / sorting unexpected | Check the warnings in the output; invalid parameters are silently reverted to defaults |
| Where is the log file | See the "Saved to …" line in stderr (system temp directory tiktok-guaikei/logs/<date>/) |
9. Environment & Support
- Environment: Node.js ≥ 16.14.0, Windows / macOS / Linux all supported;
GUAIKEI_API_TOKENis required. - Official website: TikTok Competitive Analysis & Brand Comparison (self-service token activation, usage dashboard, and API documentation).
- Changelog: references/changelog.md