FastMoss CLI
Use the fastmoss command to discover and call FastMoss tools.
Startup checks
Check the CLI is available:
fastmoss --version
If the FastMoss CLI is not installed, the command is not found, or the user
asks to update the CLI, install the current npm release:
npm install -g @fastmoss/cli@latest
This installs only the CLI. Do not install or update the Agent Skill unless
the user separately asks for it.
Then continue to the login check.
Check login status:
fastmoss whoami
If not logged in, use OAuth for normal interactive users before calling any
tools:
fastmoss login --oauth
OAuth is the recommended login method for agent clients and human-operated
terminals because the browser handles FastMoss account login, API key
selection or creation, consent, PKCE, token storage, and refresh. The agent
must not manually build the authorization URL or collect API keys in chat.
The CLI opens the browser and listens on the local loopback callback. If the
browser cannot be opened automatically, ask the user to open the URL printed
by the CLI in their browser and complete the authorization. After OAuth login,
future tool calls reuse the saved access token and automatically refresh it
with the refresh token when needed.
After the user completes OAuth authorization, verify the setup by running
the credit usage summary tool once:
FASTMOSS_CLIENT_NAME="<client-name>" FASTMOSS_CLIENT_VERSION="<client-version>" fastmoss call --tool credit_usage_summary --args '{}' --output mcp
If the current agent client cannot run the verification command directly,
ask the user to send one simple FastMoss question, such as "show my FastMoss
credit usage", so the agent can make a real tool call and confirm the
authorization works.
Use API Key login only for compatibility or non-browser automation:
- Existing users who already configured an API key can keep using it; do not
force them through OAuth.
- Use API Key login for CI, headless servers, legacy scripts, or clients that
cannot support a browser-based OAuth flow.
- In an interactive Agent client that can attach secret input to an active
terminal, start
fastmoss login in a PTY. When the CLI displays its API
key prompt, trigger the client's native secret-entry action with one field
named FastMoss API Key and write the result directly to that active
terminal. The CLI disables terminal echo while reading it.
- Never collect the key in ordinary chat, repeat or display it, place it in
command arguments, pipe it through stdin, or include it in tool arguments,
logs, plans, or replies.
- If the current client cannot securely attach user input to the active CLI
terminal and OAuth is not suitable, ask the user to complete API Key login
in their own real terminal:
fastmoss login
fastmoss login --api-key <value> remains available only for compatibility
with existing trusted automation. Do not recommend it for interactive login
because command arguments may be observable by other processes or logs.
After any first-time login path succeeds, run credit_usage_summary once to
confirm authentication, quota visibility, and MCP tool calling are working.
If verification fails because of missing auth, retry the login guidance above.
Tool workflow
Read references/tools.md to choose the most specific tool and load only its matching category file. The packaged catalog is for tool selection and offline fallback; it is not the authority for the current account's input schema.
Before every fastmoss call, run the exact tool lookup and use its returned schema to construct --args:
fastmoss tools --search <tool_name>
This lookup is mandatory whenever it is available. It gives the current tool's required fields, nesting, types, and enum values. Do not infer parameters from a similar tool or invent fields. If live lookup is unavailable, use the packaged category file as the fallback and state the limitation if the call is rejected.
Read references/tool-call.md for shell quoting, output modes, and error handling.
Put fields at the nesting shown by the schema. For example, when the schema requires filter.date_type and filter.date_value, pass them inside filter, not at the top level:
{"filter":{"date_type":"week","date_value":"2025-W01","region":"US"},"page":1,"pagesize":10}
For ranking tools, date_type selects the period and date_value is required for that completed period: day uses the prior day as YYYY-MM-DD; week uses the last completed ISO week as YYYY-Www; month uses the last completed calendar month as YYYY-MM. Never pass an in-progress day, week, or month. The exact tool schema remains authoritative because some rankings support only a subset of these values.
Every fastmoss call MUST include agent client metadata. Prefer environment variables when making one or more calls in the same shell session:
FASTMOSS_CLIENT_NAME="<client-name>" FASTMOSS_CLIENT_VERSION="<client-version>" fastmoss call --tool <tool_name> --args '<json>' --output mcp
Or pass explicit flags for a single call:
fastmoss call --client-name "<client-name>" --client-version "<client-version>" --tool <tool_name> --args '<json>' --output mcp
Use the actual client name and version when available. Do not invent a version number; if the runtime does not expose a version, use the client name and omit the version only if the CLI allows it.
Prefer --output mcp when an LLM or agent will read and reason over the tool response. Use --output data when the user needs a concise end-user payload. Use --output rpc only when debugging raw RPC responses.
Common parameter patterns
All current tools have a flattened parameter table and a generated JSON example in the matching category reference. Apply these rules before calling any of them:
| Parameter pattern |
How to pass it |
| Nested filters |
Keep the schema path in the JSON: filter.uid, filter.region, or filter.date_type means {"filter":{...}}, not a top-level field. |
| Object identity |
Use the exact ID name returned by a search or detail tool, such as uid, product_id, shop_id, video_id, or live_id; do not substitute a handle or display name. |
| Categories |
Resolve a named category with search_category_by_words before passing category_id, product_category_id, creator_category_id, or category_path. |
| Time ranges |
Use only the schema's time style: time_range_days, start_date/end_date (both YYYY-MM-DD), or ranking date_type/date_value. Do not mix styles unless the schema exposes both. |
| Rankings |
Use a completed period only: day → prior YYYY-MM-DD; week → last completed YYYY-Www; month → last completed YYYY-MM. Confirm supported periods with the exact tool lookup. |
| Pagination and sorting |
Pass page and pagesize at the top level when the schema lists them. Their maximum is 10. orderby is an array; use only fields and sort shapes returned by the schema. |
| Ranges and enums |
Preserve object shapes such as {"min": number, "max": number} and use only the enum values returned by tools --search. |
Leaderboard example
The same time-field structure applies to creator, product, shop, market, and agency leaderboards whenever their exact schema includes it. For a weekly ecommerce-creator leaderboard, verify the live schema first, then pass the required time fields inside filter:
fastmoss tools --search creator_rank_top_ecommerce
FASTMOSS_CLIENT_NAME="<client-name>" FASTMOSS_CLIENT_VERSION="<client-version>" fastmoss call --tool creator_rank_top_ecommerce --args '{"filter":{"date_type":"week","date_value":"2025-W01","region":"US"},"page":1,"pagesize":10}' --output mcp
2025-W01 is an example of the required ISO-week format; replace it with the latest completed week or the period the user requested. The generated references provide the exact fields for every current leaderboard and non-leaderboard tool.
If the analysis result needs FastMoss detail-page links, call fastmoss_detail_url_examples first to get the link assembly rules, then build links from the returned examples and IDs in the analysis result.
References
references/cli.md: CLI command reference.references/tool-call.md: safe calling patterns, quoting, output modes, and error handling.references/tools.md: static FastMoss tool catalog index. Read the matching category file from this index instead of loading all tools at once.references/tools-advertising.md: advertising tool details.references/tools-agency.md: MCN agency tool details.references/tools-creator.md: creator tool details.references/tools-product.md: product tool details.references/tools-shop.md: shop tool details.references/tools-market.md: market insight tool details.references/tools-live.md: live-session tool details.references/tools-video.md: video tool details.references/tools-auxiliary-knowledge.md: auxiliary and FastMoss knowledge-base tool details.
1---2name: fastmoss-23description: Use when working with FastMoss CLI, FastMoss MCP tools, TikTok Shop product, creator, shop, MCN agency, video, ad, category, or market data, or when the user asks an agent to call FastMoss tools from the command line.4---56# FastMoss CLI78Use the `fastmoss` command to discover and call FastMoss tools.910## Startup checks11121. Check the CLI is available:1314 ```bash15 fastmoss --version16 ```1718 If the FastMoss CLI is not installed, the command is not found, or the user19 asks to update the CLI, install the current npm release:2021 ```bash22 npm install -g @fastmoss/cli@latest23 ```2425 This installs only the CLI. Do not install or update the Agent Skill unless26 the user separately asks for it.2728 Then continue to the login check.29302. Check login status:3132 ```bash33 fastmoss whoami34 ```35363. If not logged in, use OAuth for normal interactive users before calling any37 tools:3839 ```bash40 fastmoss login --oauth41 ```4243 OAuth is the recommended login method for agent clients and human-operated44 terminals because the browser handles FastMoss account login, API key45 selection or creation, consent, PKCE, token storage, and refresh. The agent46 must not manually build the authorization URL or collect API keys in chat.4748 The CLI opens the browser and listens on the local loopback callback. If the49 browser cannot be opened automatically, ask the user to open the URL printed50 by the CLI in their browser and complete the authorization. After OAuth login,51 future tool calls reuse the saved access token and automatically refresh it52 with the refresh token when needed.5354 After the user completes OAuth authorization, verify the setup by running55 the credit usage summary tool once:5657 ```bash58 FASTMOSS_CLIENT_NAME="<client-name>" FASTMOSS_CLIENT_VERSION="<client-version>" fastmoss call --tool credit_usage_summary --args '{}' --output mcp59 ```6061 If the current agent client cannot run the verification command directly,62 ask the user to send one simple FastMoss question, such as "show my FastMoss63 credit usage", so the agent can make a real tool call and confirm the64 authorization works.65664. Use API Key login only for compatibility or non-browser automation:6768 - Existing users who already configured an API key can keep using it; do not69 force them through OAuth.70 - Use API Key login for CI, headless servers, legacy scripts, or clients that71 cannot support a browser-based OAuth flow.72 - In an interactive Agent client that can attach secret input to an active73 terminal, start `fastmoss login` in a PTY. When the CLI displays its API74 key prompt, trigger the client's native secret-entry action with one field75 named `FastMoss API Key` and write the result directly to that active76 terminal. The CLI disables terminal echo while reading it.77 - Never collect the key in ordinary chat, repeat or display it, place it in78 command arguments, pipe it through stdin, or include it in tool arguments,79 logs, plans, or replies.80 - If the current client cannot securely attach user input to the active CLI81 terminal and OAuth is not suitable, ask the user to complete API Key login82 in their own real terminal:8384 ```bash85 fastmoss login86 ```8788 - `fastmoss login --api-key <value>` remains available only for compatibility89 with existing trusted automation. Do not recommend it for interactive login90 because command arguments may be observable by other processes or logs.91925. After any first-time login path succeeds, run `credit_usage_summary` once to93 confirm authentication, quota visibility, and MCP tool calling are working.94 If verification fails because of missing auth, retry the login guidance above.9596## Tool workflow97981. Read `references/tools.md` to choose the most specific tool and load only its matching category file. The packaged catalog is for tool selection and offline fallback; it is not the authority for the current account's input schema.992. **Before every `fastmoss call`, run the exact tool lookup and use its returned schema to construct `--args`:**100101 ```bash102 fastmoss tools --search <tool_name>103 ```104105 This lookup is mandatory whenever it is available. It gives the current tool's required fields, nesting, types, and enum values. Do not infer parameters from a similar tool or invent fields. If live lookup is unavailable, use the packaged category file as the fallback and state the limitation if the call is rejected.1063. Read `references/tool-call.md` for shell quoting, output modes, and error handling.1074. Put fields at the nesting shown by the schema. For example, when the schema requires `filter.date_type` and `filter.date_value`, pass them inside `filter`, not at the top level:108109 ```json110 {"filter":{"date_type":"week","date_value":"2025-W01","region":"US"},"page":1,"pagesize":10}111 ```112113 For ranking tools, `date_type` selects the period and `date_value` is required for that completed period: `day` uses the prior day as `YYYY-MM-DD`; `week` uses the last completed ISO week as `YYYY-Www`; `month` uses the last completed calendar month as `YYYY-MM`. Never pass an in-progress day, week, or month. The exact tool schema remains authoritative because some rankings support only a subset of these values.1145. Every `fastmoss call` MUST include agent client metadata. Prefer environment variables when making one or more calls in the same shell session:115116 ```bash117 FASTMOSS_CLIENT_NAME="<client-name>" FASTMOSS_CLIENT_VERSION="<client-version>" fastmoss call --tool <tool_name> --args '<json>' --output mcp118 ```119120 Or pass explicit flags for a single call:121122 ```bash123 fastmoss call --client-name "<client-name>" --client-version "<client-version>" --tool <tool_name> --args '<json>' --output mcp124 ```125126 Use the actual client name and version when available. Do not invent a version number; if the runtime does not expose a version, use the client name and omit the version only if the CLI allows it.127128Prefer `--output mcp` when an LLM or agent will read and reason over the tool response. Use `--output data` when the user needs a concise end-user payload. Use `--output rpc` only when debugging raw RPC responses.129130### Common parameter patterns131132All current tools have a flattened parameter table and a generated JSON example in the matching category reference. Apply these rules before calling any of them:133134| Parameter pattern | How to pass it |135|---|---|136| Nested filters | Keep the schema path in the JSON: `filter.uid`, `filter.region`, or `filter.date_type` means `{"filter":{...}}`, not a top-level field. |137| Object identity | Use the exact ID name returned by a search or detail tool, such as `uid`, `product_id`, `shop_id`, `video_id`, or `live_id`; do not substitute a handle or display name. |138| Categories | Resolve a named category with `search_category_by_words` before passing `category_id`, `product_category_id`, `creator_category_id`, or `category_path`. |139| Time ranges | Use only the schema's time style: `time_range_days`, `start_date`/`end_date` (both `YYYY-MM-DD`), or ranking `date_type`/`date_value`. Do not mix styles unless the schema exposes both. |140| Rankings | Use a completed period only: `day` → prior `YYYY-MM-DD`; `week` → last completed `YYYY-Www`; `month` → last completed `YYYY-MM`. Confirm supported periods with the exact tool lookup. |141| Pagination and sorting | Pass `page` and `pagesize` at the top level when the schema lists them. Their maximum is 10. `orderby` is an array; use only fields and sort shapes returned by the schema. |142| Ranges and enums | Preserve object shapes such as `{"min": number, "max": number}` and use only the enum values returned by `tools --search`. |143144### Leaderboard example145146The same time-field structure applies to creator, product, shop, market, and agency leaderboards whenever their exact schema includes it. For a weekly ecommerce-creator leaderboard, verify the live schema first, then pass the required time fields inside `filter`:147148```bash149fastmoss tools --search creator_rank_top_ecommerce150FASTMOSS_CLIENT_NAME="<client-name>" FASTMOSS_CLIENT_VERSION="<client-version>" fastmoss call --tool creator_rank_top_ecommerce --args '{"filter":{"date_type":"week","date_value":"2025-W01","region":"US"},"page":1,"pagesize":10}' --output mcp151```152153`2025-W01` is an example of the required ISO-week format; replace it with the latest completed week or the period the user requested. The generated references provide the exact fields for every current leaderboard and non-leaderboard tool.154155If the analysis result needs FastMoss detail-page links, call `fastmoss_detail_url_examples` first to get the link assembly rules, then build links from the returned examples and IDs in the analysis result.156157## References158159- `references/cli.md`: CLI command reference.160- `references/tool-call.md`: safe calling patterns, quoting, output modes, and error handling.161- `references/tools.md`: static FastMoss tool catalog index. Read the matching category file from this index instead of loading all tools at once.162- `references/tools-advertising.md`: advertising tool details.163- `references/tools-agency.md`: MCN agency tool details.164- `references/tools-creator.md`: creator tool details.165- `references/tools-product.md`: product tool details.166- `references/tools-shop.md`: shop tool details.167- `references/tools-market.md`: market insight tool details.168- `references/tools-live.md`: live-session tool details.169- `references/tools-video.md`: video tool details.170- `references/tools-auxiliary-knowledge.md`: auxiliary and FastMoss knowledge-base tool details.
fastmoss