@fastmoss/cli 0.1.6 → 0.1.14

package/README.md

@@ -1,226 +1,171 @@
-# FastMoss CLI
+# @fastmoss/cli
 
 [中文文档](./README.zh-CN.md)
 
-FastMoss CLI lets terminals and AI agents discover and call FastMoss MCP tools for TikTok Shop product research, creator discovery, shop analysis, ad analysis, market insight, video/live analysis, and FastMoss knowledge-base lookup.
+`@fastmoss/cli` installs the `fastmoss` command. The npm package resolves an exact-version platform package and never downloads a binary at install time or runtime.
 
-Use the CLI together with the FastMoss CLI Agent Skill:
+<!-- FASTMOSS_INSTALLATION_START -->
+## Installation
 
-- `@fastmoss/cli` installs the `fastmoss` command and executes tool calls.
-- `npx skills add FastMoss/cli` installs the Agent Skill so your agent knows which FastMoss tools exist, when to use them, and how to call them.
+The CLI and Agent Skill are independent. Installing either one never installs the other.
 
-Install CLI:
+### npm
 
-```bash
-npm install -g @fastmoss/cli
-```
-
-Install Skill separately:
+Install only the CLI:
 
 ```bash
-npx skills add FastMoss/cli -y -g
-npx skills add FastMoss/cli --agent claude-code
-# If your skills CLI supports --client:
-npx skills add FastMoss/cli --client claude
+npm install -g @fastmoss/cli@latest
 ```
 
-## About FastMoss
-
-[FastMoss](https://www.fastmoss.com/) is a TikTok data analytics platform for global TikTok brands, merchants, service providers, creators, and operation teams. It helps users understand market trends, discover bestselling categories and products, find creators and agencies, monitor competitor shops, analyze ad investment, and study the livestream ecosystem.
-
-FastMoss provides big-data analytics centered on TikTok and TikTok Shop, covering livestreams, products, shops, creators, ads, videos, music, hashtags, and more. Its data spans major TikTok commercial markets and regions including the United States, United Kingdom, Indonesia, Vietnam, the Philippines, Thailand, Malaysia, Spain, Mexico, France, Germany, Brazil, and others.
-
-## Install
-
-Run without installing:
+Run it temporarily without a global install:
 
 ```bash
-npx @fastmoss/cli
+npx -y @fastmoss/cli@latest
 ```
 
-Install globally:
+Install or update only the Agent Skill:
 
 ```bash
-npm install -g @fastmoss/cli
-fastmoss
+npx -y @fastmoss/skill@latest
 ```
 
-After global installation, the command name is `fastmoss`. If your shell prints `command not found: fastmoss`, make sure your npm global bin directory is in `PATH`.
+The Skill command is non-interactive, so it can be pasted into an Agent conversation for the Agent to execute. By default it installs `fastmoss-cli` for Codex, Claude, and generic Agents, then prints the installed `SKILL.md` paths and a current-conversation handoff.
 
-If your npm configuration blocks lifecycle scripts, allow this package's postinstall script to predownload during install:
+Target or remove a specific installation:
 
 ```bash
-npm install -g --allow-scripts=@fastmoss/cli @fastmoss/cli
+npx -y @fastmoss/skill@latest --agent codex
+npx -y @fastmoss/skill@latest --agent claude
+npx -y @fastmoss/skill@latest --agent agents
+npx -y @fastmoss/skill@latest --agent all
+npx -y @fastmoss/skill@latest uninstall --agent all
 ```
 
-## API Key and Credits
+Set `FASTMOSS_SKILL_DIR` to install into one custom skills root. npm installation uses only the configured npm registry and does not download from GitHub.
 
-FastMoss tool calls require an API key and consume credits. Visit the [FastMoss Developer Platform](https://developers.fastmoss.com/mcp/overview.html) to sign in, create an MCP API key, view usage, and manage credits.
-
-Typical setup:
+### GitHub clone
 
 ```bash
-fastmoss login --api-key <your-api-key>
-fastmoss whoami
+git clone --depth 1 https://github.com/FastMoss/cli.git
+cd cli
+./install.sh --cli
+./install.sh --skill
+./install.sh --all
 ```
 
-If your credits are insufficient, recharge or upgrade from the developer platform billing/pricing pages. Pricing and credit rules are documented in the [FastMoss MCP pricing guide](https://developers.fastmoss.com/mcp/pricing.html).
+On Windows PowerShell:
+
+```powershell
+git clone --depth 1 https://github.com/FastMoss/cli.git
+cd cli
+.\install.ps1 -Cli
+.\install.ps1 -Skill
+.\install.ps1 -All
+```
 
-## Commands
+`--all` and `-All` run the two independent installers in sequence. Clone and GitHub Release bundles install only from local files after download; they do not invoke npm or fetch additional files.
+<!-- FASTMOSS_INSTALLATION_END -->
 
-Check version and help:
+## Usage
 
 ```bash
 fastmoss --version
 fastmoss help
-```
-
-Authentication and local config:
-
-```bash
 fastmoss login --api-key <your-api-key>
-fastmoss logout
-fastmoss whoami
-fastmoss set api-key <your-api-key>
-fastmoss clear api-key
-fastmoss set language zh
-fastmoss set language en
-fastmoss show config
-fastmoss show auth
-```
-
-Discover tools:
-
-```bash
 fastmoss tools
-fastmoss tools --json
-fastmoss tools --search <tool_name>
-```
-
-Call tools:
-
-```bash
 fastmoss call --tool <tool_name> --args '<json>' --output mcp
-fastmoss <tool_name> --args '<json>' --output mcp
 ```
 
-Use `--output mcp` when an LLM or agent will read the result. Use `--output data` when you want a concise payload for terminal use. Use `--output rpc` only for raw RPC debugging.
-
-Common flags for networked commands:
-
-```bash
---api-key <api-key>
---base-url <url>
---timeout <seconds>
---insecure-skip-tls
-```
-
-## Supported Tools
-
-The packaged Agent Skill includes a static tool catalog. Run `fastmoss tools` or `fastmoss tools --json` to check the live tool list available to your account.
-
-| Category | Name | Title |
-|---|---|---|
-| Advertising | `ad_data_overview` | Ad data overview |
-| Advertising | `ad_search` | Ad search |
-| Creator | `creator_cargo_summary` | Creator ecommerce summary |
-| Creator | `creator_data_trends` | Creator data trends |
-| Creator | `creator_fans_distribution` | Creator fans distribution |
-| Creator | `creator_product_list` | Creator product list |
-| Creator | `creator_profile_overview` | Creator profile overview |
-| Creator | `creator_rank_top_ecommerce` | Top ecommerce creators |
-| Creator | `creator_rank_top_growth` | Top creator follower growth |
-| Creator | `creator_rank_top_potential` | Top potential creators |
-| Creator | `creator_search` | Creator search |
-| Creator | `creator_video_analysis` | Creator video analysis |
-| Auxiliary and knowledge | `fastmoss_detail_url_examples` | FastMoss Detail URL Examples |
-| Auxiliary and knowledge | `live_detail_analysis` | Live detail analysis and category breakdown |
-| Auxiliary and knowledge | `live_products_list` | Live promoted product list |
-| Auxiliary and knowledge | `live_search` | Live search |
-| Market insight | `market_category_analysis` | Category market analysis |
-| Market insight | `market_category_author_sales_matrix` | Category creator sales matrix |
-| Market insight | `market_category_ranking` | Category market ranking |
-| Product | `product_category_info` | Product category list |
-| Product | `product_creator_analysis` | Product creator analysis and creator list |
-| Product | `product_detail_info` | Product detail info |
-| Product | `product_investment` | Product ad investment analysis |
-| Product | `product_overview` | Product overview |
-| Product | `product_rank_new_listed` | New listed product ranking |
-| Product | `product_rank_top_selling` | Top selling products |
-| Product | `product_review_list` | Product review list |
-| Product | `product_sales_trend` | Product sales trend |
-| Product | `product_search` | Product search |
-| Product | `product_sku` | Product SKU analysis |
-| Product | `product_video_list` | Product video list |
-| Auxiliary and knowledge | `search_category_by_words` | Search TikTok Product Category by Keywords |
-| Auxiliary and knowledge | `search_fastmoss_documents` | FastMoss Knowledge Base Search |
-| Shop | `shop_base_info` | Shop base info |
-| Shop | `shop_creator_analysis` | Shop creator analysis and creator list |
-| Shop | `shop_data_trends` | Shop data trends |
-| Shop | `shop_investment_analysis` | Shop ad investment analysis |
-| Shop | `shop_live_analysis` | Shop live analysis and live list |
-| Shop | `shop_product_analysis` | Shop product analysis and product list |
-| Shop | `shop_rank_top_selling` | Top selling shops |
-| Shop | `shop_sale_analysis` | Shop sales analysis |
-| Shop | `shop_search` | Shop search |
-| Shop | `shop_video_analysis` | Shop video analysis and video list |
-| Auxiliary and knowledge | `video_data_trends` | Video data trends |
-| Auxiliary and knowledge | `video_detail_analysis` | Video detail analysis and product list |
-| Auxiliary and knowledge | `video_script_info` | Video subtitle script |
-| Auxiliary and knowledge | `video_search` | Video search |
-
-## Binary Download
-
-This package installs the `fastmoss` command. It does not bundle the Go binary itself. Instead, it downloads the matching `fastmoss` binary from GitHub Releases, stores it in a local cache directory, and then forwards all CLI arguments to that binary.
-
-During `npm install`, the package tries to predownload the matching binary for the current platform. If the download fails, installation still completes and the wrapper will retry the download on first run with a visible download message.
-
-The package downloads the current platform's binary from the public GitHub release repository configured in `package.json`.
-
-If install-time download is blocked or fails, the first `fastmoss` run will download the binary again. You should see output similar to:
-
-```text
-Downloading fastmoss 0.1.1 from https://github.com/FastMoss/cli/releases/download/...
-```
-
-You can skip the install-time download and let the first run download the binary:
-
-```bash
-FASTMOSS_SKIP_DOWNLOAD=1 npm install -g @fastmoss/cli
-```
-
-For internal debugging or private release mirrors, override the base URL:
-
-```bash
-FASTMOSS_DOWNLOAD_BASE_URL=https://downloads.example.com/releases npx @fastmoss/cli
-```
-
-## Cache Directory
-
-The downloaded binary is cached here by default:
-
-```text
-~/.fastmoss/bin/<version>/<platform>/
-```
-
-Override the cache directory:
-
-```bash
-FASTMOSS_CACHE_DIR=/custom/cache/dir npx @fastmoss/cli
-```
-
-## Supported Platforms
-
-- macOS `amd64`
-- macOS `arm64`
-- Linux `amd64`
-- Linux `arm64`
-- Windows `amd64`
-
-The wrapper will request one of these asset names depending on platform:
-
-- `fastmoss-darwin-amd64`
-- `fastmoss-darwin-arm64`
-- `fastmoss-linux-amd64`
-- `fastmoss-linux-arm64`
-- `fastmoss-windows-amd64.exe`
+## CLI Tool Catalog
+
+### Advertising Tools
+
+| Tool | Description |
+|---|---|
+| `ad_data_overview` | Use when the user has a video_id and wants ad spend, ROAS, play, engagement, follower, and commerce performance over a date range. |
+| `ad_search` | Use when the user wants active ad creatives or needs to filter ads by country, category, landing page, spend, ROAS, plays, or run days. Returns ad, creator, shop, products, and performance sections. |
+
+### Agency Tools
+
+| Tool | Description |
+|---|---|
+| `agency_creator_analysis` | Use when the user wants agency creator structure, follower tiers, and individual collaborators. Returns distributions and a paginated creator list. |
+| `agency_product_analysis` | Use for agency product-category and price-band structure. Use agency_product_list for individual products. |
+| `agency_product_list` | Use when the user wants individual products promoted through an agency. Supports category, price, period, sorting, and pagination. |
+| `agency_profile_overview` | Use when the user wants an agency profile, historical performance, and recent 7/28/90-day data overview. |
+| `agency_rank_top` | Use when the user wants leading MCN agencies in a market. Returns weekly or monthly agency rankings and period performance. |
+| `agency_search` | Use when the user has an agency name or market clue but no agency_id. Returns matching agencies and recent 7-day performance. |
+| `agency_shop_analysis` | Use when the user wants agency collaborating-shop totals and individual shop performance. |
+
+### Creator Tools
+
+| Tool | Description |
+|---|---|
+| `creator_cargo_summary` | Use when the user wants a creator video-vs-live selling split and main promoted categories. |
+| `creator_data_trends` | Use when the user asks about creator follower, engagement, or commerce trends. Select field_type; returns daily series and period totals. |
+| `creator_fans_distribution` | Use when the user wants to check whether a creator audience matches a target market. Returns age, gender, location, and top segments. |
+| `creator_product_list` | Use when the user wants a creator showcase product list. Returns product GMV, units sold, category, price, commission, shop info, and time_range_days. |
+| `creator_profile_overview` | Use when the user wants a creator snapshot or partnership check. Returns profile and performance_overview; GMV/rankings are mostly historical cumulative, so use creator_search day28_gmv for current activity. |
+| `creator_rank_top_ecommerce` | Use when the user wants top ecommerce creators. Returns creator and ranking_metrics; date_value is returned as YYYY-Www for weekly rankings. |
+| `creator_rank_top_growth` | Use when the user wants fast-growing creators. Returns creator and growth_metrics; date_value is returned as YYYY-Www for weekly rankings. |
+| `creator_rank_top_potential` | Use when the user wants creators with ecommerce potential. Returns creator, potential_metrics, and audience_summary; date_value is returned as YYYY-Www for weekly rankings. |
+| `creator_search` | Use when the user has no UID and provides a nickname, keyword, niche, or region. Returns creator, commerce_summary, and audience_summary; day28_gmv is the key current-activity metric for tiering; has_email as a boolean, not the email address itself. |
+| `creator_video_analysis` | Use when the user wants creator content direction, tags, and selling videos. Returns video_tag_summary and video_list with interaction_rate_percent and linked_products so the model does not confuse video performance with product performance. |
+
+### Product Tools
+
+| Tool | Description |
+|---|---|
+| `product_category_info` | Use when the user needs the product category tree or category levels. Prefer search_category_by_words for natural-language category terms. |
+| `product_creator_analysis` | Use when the user wants who sells a product or the creator structure. Returns creator_summary with follower_tier_distribution and creator_category_distribution, plus linked_creators with creator, product_contribution, creator_cumulative_performance, and audience_summary. |
+| `product_detail_info` | Use when the user wants product basics, shop, price, rating, logistics, images, or ad status. Returns product and shop; detail_url points to TikTok. |
+| `product_investment` | Use when the user asks about product ads, spend, ROAS, or daily paid-traffic changes. Returns ad_performance_summary and daily_ad_performance_trend; ad_gmv is ad-attributed. |
+| `product_overview` | Use when the user wants product channel attribution, lifecycle/momentum, or ad-vs-organic structure. Returns period_summary, daily_trend, ads_distribution, channel_distribution, and content_distribution. |
+| `product_rank_new_listed` | Use when the user wants recently listed hot products. Returns FastMoss new-product ranking, first_3d_gmv/units_sold, and total_gmv/units_sold; new means listed within 30 days. |
+| `product_rank_top_selling` | Use when the user wants bestsellers or top products. Returns period_gmv/units_sold, total_gmv/units_sold, and units_sold_growth_rate_percent. |
+| `product_review_list` | Use when the user wants product reviews or buyer feedback. Returns review list and count; supports time_range_days and rating/create_time/review_id sorting. |
+| `product_sales_trend` | Use when the user wants a product GMV/units trend or traction check. Returns period_summary and daily_trend with period_gmv, period_units_sold, daily_gmv, and daily_units_sold. |
+| `product_search` | Use when the user has no product_id and provides a name, keyword, price band, category, bestseller clue, or new-product clue. Returns product, sales_summary, distribution_summary, and shop. |
+| `product_sku` | Use when the user wants SKU sales share, inventory share, or SKU health. Returns SKU-level sales and inventory shares. |
+| `product_video_list` | Use when the user wants videos selling a product, high-play videos, or paid-vs-organic video traffic. Filter with is_ad; returns GMV, plays, video_desc, and fastmoss_url. |
+
+### Shop Tools
+
+| Tool | Description |
+|---|---|
+| `shop_base_info` | Use when the user wants a shop snapshot, store type, rating, or profile. Returns cumulative GMV/units, ranks, age, product count, and creator/video/live counts. |
+| `shop_creator_analysis` | Use when the user wants shop collaborators, creator tiers, or video-vs-live selling structure. Returns creator list and distributions. |
+| `shop_data_trends` | Use when the user wants recent shop GMV, units, creator, live, video, or active-product trends. Returns daily trends. |
+| `shop_investment_analysis` | Use when the user asks about shop ads, spend, ROAS, ad GMV, or promoted assets. Returns ad estimates and daily changes. |
+| `shop_live_analysis` | Use when the user wants shop live performance, shop-live vs affiliate-live structure, or live sessions. |
+| `shop_product_analysis` | Use when the user wants shop categories, price bands, product mix, or product details. Returns distributions and product list. |
+| `shop_rank_top_selling` | Use when the user wants top shops in a market or category. Returns shop ranking and ecommerce metrics. |
+| `shop_sale_analysis` | Use when the user wants shop sales by short video, live, product card, creator, or self-operated channels. Returns channel_distribution and content_distribution. |
+| `shop_search` | Use when the user has no seller_id and provides a shop name, keyword, or region. Returns matching shops. |
+| `shop_video_analysis` | Use when the user wants shop selling videos, video performance, or ad status. |
+
+### Market Insight Tools
+
+| Tool | Description |
+|---|---|
+| `market_category_analysis` | Use when the user wants category size, growth, competition, or opportunity. analysis_type basic_metrics returns category, scale_metrics, growth_metrics, concentration_metrics; sales_trends returns trend_series; price_distribution returns sales_price_distribution with left-open right-closed price bands and sub_category_units_sold_total. |
+| `market_category_author_sales_matrix` | Use when the user wants category sales contribution by creator follower_tier. Returns creator_count, category_gmv, gmv_share_percent, units_sold, and avg_creator_gmv. |
+| `market_category_ranking` | Use when the user wants category ranking, growth, or concentration. Returns ranking_scope and ranked_categories; no category_id means level-1 category ranking, and a level-1 category_id means level-2 subcategory ranking. |
+
+### Auxiliary and Knowledge Base Tools
+
+| Tool | Description |
+|---|---|
+| `fastmoss_detail_url_examples` | Use when the AI needs FastMoss detail-page links. Takes no arguments and returns product, creator, shop, video, and live URL templates. |
+| `live_detail_analysis` | Use when the user wants one live session info, creator, key performance, and category breakdown. |
+| `live_products_list` | Use when the user wants products sold in a live session or high GMV/units within this live session. Returns live_units_sold, live_gmv, commission_rate_percent, sales_timeline only when pagesize <= 10, and shop_cumulative_units_sold. |
+| `live_search` | Use when the user has no room_id and provides a live title, host, or shop. Returns live, creator, and performance_summary. |
+| `search_category_by_words` | Use when the user knows a product/category term but does not have the category_id yet. Returns matched TikTok product category IDs and Chinese category paths. |
+| `search_fastmoss_documents` | Use when the user asks about FastMoss rules, features, terms, or operations rather than real-time business data. Returns knowledge snippets and documents. |
+| `video_data_trends` | Use when the user wants one video play, like, comment, or share trends. Returns daily interaction trends. |
+| `video_detail_analysis` | Use when the user wants one video basics, plays, engagement, interaction rate, IPM, and linked products. |
+| `video_script_info` | Use when the user wants video subtitles or line-by-line spoken copy. Returns start/end time and text; empty subtitles can fall back to video_desc. |
+| `video_search` | Use when the user has no video_id and provides video keywords, title, or creator. Returns matching videos. |
+
+
+This package only installs the CLI. Use `@fastmoss/skill` when you want an Agent Skill that teaches an agent how and when to call the CLI.