@fastmoss/cli 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +163 -31
  2. package/README.zh-CN.md +210 -0
  3. package/package.json +3 -2
package/README.md CHANGED
@@ -1,18 +1,28 @@
1
- # @fastmoss/cli
1
+ # FastMoss CLI
2
2
 
3
- FastMoss CLI launcher for npm and npx.
3
+ [中文文档](./README.zh-CN.md)
4
4
 
5
- This package does not bundle the Go binary itself. On first run 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.
5
+ 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.
6
6
 
7
- 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.
7
+ Use the CLI together with the FastMoss CLI Agent Skill:
8
8
 
9
- If your npm configuration blocks lifecycle scripts, allow this package's postinstall script to predownload during install:
9
+ - `@fastmoss/cli` installs the `fastmoss` command and executes tool calls.
10
+ - `npx skills add FastMoss/cli -y -g` installs the Agent Skill so your agent knows which FastMoss tools exist, when to use them, and how to call them.
11
+
12
+ For agent workflows, install both:
10
13
 
11
14
  ```bash
12
- npm install -g --allow-scripts=@fastmoss/cli @fastmoss/cli
15
+ npm install -g @fastmoss/cli
16
+ npx skills add FastMoss/cli -y -g
13
17
  ```
14
18
 
15
- ## Usage
19
+ ## About FastMoss
20
+
21
+ [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.
22
+
23
+ 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.
24
+
25
+ ## Install
16
26
 
17
27
  Run without installing:
18
28
 
@@ -27,52 +37,178 @@ npm install -g @fastmoss/cli
27
37
  fastmoss
28
38
  ```
29
39
 
30
- Common examples:
40
+ 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`.
41
+
42
+ If your npm configuration blocks lifecycle scripts, allow this package's postinstall script to predownload during install:
43
+
44
+ ```bash
45
+ npm install -g --allow-scripts=@fastmoss/cli @fastmoss/cli
46
+ ```
47
+
48
+ ## API Key and Credits
49
+
50
+ 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.
51
+
52
+ Typical setup:
53
+
54
+ ```bash
55
+ fastmoss login --api-key <your-api-key>
56
+ fastmoss whoami
57
+ ```
58
+
59
+ 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).
60
+
61
+ ## Commands
62
+
63
+ Check version and help:
64
+
65
+ ```bash
66
+ fastmoss --version
67
+ fastmoss help
68
+ ```
69
+
70
+ Authentication and local config:
71
+
72
+ ```bash
73
+ fastmoss login --api-key <your-api-key>
74
+ fastmoss logout
75
+ fastmoss whoami
76
+ fastmoss set api-key <your-api-key>
77
+ fastmoss clear api-key
78
+ fastmoss set language zh
79
+ fastmoss set language en
80
+ fastmoss show config
81
+ fastmoss show auth
82
+ ```
83
+
84
+ Discover tools:
31
85
 
32
86
  ```bash
33
87
  fastmoss tools
34
- fastmoss call --tool creator_search --args '{"keywords":"beauty","region":"US","page":1,"pagesize":10}'
35
- fastmoss stdio
88
+ fastmoss tools --json
89
+ fastmoss tools --search <tool_name>
36
90
  ```
37
91
 
38
- ## Supported Platforms
92
+ Call tools:
39
93
 
40
- - macOS `amd64`
41
- - macOS `arm64`
42
- - Linux `amd64`
43
- - Linux `arm64`
44
- - Windows `amd64`
94
+ ```bash
95
+ fastmoss call --tool <tool_name> --args '<json>' --output mcp
96
+ fastmoss <tool_name> --args '<json>' --output mcp
97
+ ```
45
98
 
46
- ## Cache Directory
99
+ 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.
47
100
 
48
- The downloaded binary is cached here by default:
101
+ Common flags for networked commands:
102
+
103
+ ```bash
104
+ --api-key <api-key>
105
+ --base-url <url>
106
+ --timeout <seconds>
107
+ --insecure-skip-tls
108
+ ```
109
+
110
+ ## Supported Tools
111
+
112
+ 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.
113
+
114
+ | Category | Name | Title |
115
+ |---|---|---|
116
+ | Advertising | `ad_data_overview` | Ad data overview |
117
+ | Advertising | `ad_search` | Ad search |
118
+ | Creator | `creator_cargo_summary` | Creator ecommerce summary |
119
+ | Creator | `creator_data_trends` | Creator data trends |
120
+ | Creator | `creator_fans_distribution` | Creator fans distribution |
121
+ | Creator | `creator_product_list` | Creator product list |
122
+ | Creator | `creator_profile_overview` | Creator profile overview |
123
+ | Creator | `creator_rank_top_ecommerce` | Top ecommerce creators |
124
+ | Creator | `creator_rank_top_growth` | Top creator follower growth |
125
+ | Creator | `creator_rank_top_potential` | Top potential creators |
126
+ | Creator | `creator_search` | Creator search |
127
+ | Creator | `creator_video_analysis` | Creator video analysis |
128
+ | Auxiliary and knowledge | `fastmoss_detail_url_examples` | FastMoss Detail URL Examples |
129
+ | Auxiliary and knowledge | `live_detail_analysis` | Live detail analysis and category breakdown |
130
+ | Auxiliary and knowledge | `live_products_list` | Live promoted product list |
131
+ | Auxiliary and knowledge | `live_search` | Live search |
132
+ | Market insight | `market_category_analysis` | Category market analysis |
133
+ | Market insight | `market_category_author_sales_matrix` | Category creator sales matrix |
134
+ | Market insight | `market_category_ranking` | Category market ranking |
135
+ | Product | `product_category_info` | Product category list |
136
+ | Product | `product_creator_analysis` | Product creator analysis and creator list |
137
+ | Product | `product_detail_info` | Product detail info |
138
+ | Product | `product_investment` | Product ad investment analysis |
139
+ | Product | `product_overview` | Product overview |
140
+ | Product | `product_rank_new_listed` | New listed product ranking |
141
+ | Product | `product_rank_top_selling` | Top selling products |
142
+ | Product | `product_review_list` | Product review list |
143
+ | Product | `product_sales_trend` | Product sales trend |
144
+ | Product | `product_search` | Product search |
145
+ | Product | `product_sku` | Product SKU analysis |
146
+ | Product | `product_video_list` | Product video list |
147
+ | Auxiliary and knowledge | `search_category_by_words` | Search TikTok Product Category by Keywords |
148
+ | Auxiliary and knowledge | `search_fastmoss_documents` | FastMoss Knowledge Base Search |
149
+ | Shop | `shop_base_info` | Shop base info |
150
+ | Shop | `shop_creator_analysis` | Shop creator analysis and creator list |
151
+ | Shop | `shop_data_trends` | Shop data trends |
152
+ | Shop | `shop_investment_analysis` | Shop ad investment analysis |
153
+ | Shop | `shop_live_analysis` | Shop live analysis and live list |
154
+ | Shop | `shop_product_analysis` | Shop product analysis and product list |
155
+ | Shop | `shop_rank_top_selling` | Top selling shops |
156
+ | Shop | `shop_sale_analysis` | Shop sales analysis |
157
+ | Shop | `shop_search` | Shop search |
158
+ | Shop | `shop_video_analysis` | Shop video analysis and video list |
159
+ | Auxiliary and knowledge | `video_data_trends` | Video data trends |
160
+ | Auxiliary and knowledge | `video_detail_analysis` | Video detail analysis and product list |
161
+ | Auxiliary and knowledge | `video_script_info` | Video subtitle script |
162
+ | Auxiliary and knowledge | `video_search` | Video search |
163
+
164
+ ## Binary Download
165
+
166
+ 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.
167
+
168
+ 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.
169
+
170
+ The package downloads the current platform's binary from the public GitHub release repository configured in `package.json`.
171
+
172
+ If install-time download is blocked or fails, the first `fastmoss` run will download the binary again. You should see output similar to:
49
173
 
50
174
  ```text
51
- ~/.fastmoss/bin/<version>/<platform>/
175
+ Downloading fastmoss 0.1.1 from https://github.com/FastMoss/cli/releases/download/...
52
176
  ```
53
177
 
54
- You can override the cache directory:
178
+ You can skip the install-time download and let the first run download the binary:
55
179
 
56
180
  ```bash
57
- FASTMOSS_CACHE_DIR=/custom/cache/dir npx @fastmoss/cli
181
+ FASTMOSS_SKIP_DOWNLOAD=1 npm install -g @fastmoss/cli
58
182
  ```
59
183
 
60
- You can skip the install-time download:
184
+ For internal debugging or private release mirrors, override the base URL:
61
185
 
62
186
  ```bash
63
- FASTMOSS_SKIP_DOWNLOAD=1 npm install -g @fastmoss/cli
187
+ FASTMOSS_DOWNLOAD_BASE_URL=https://downloads.example.com/releases npx @fastmoss/cli
64
188
  ```
65
189
 
66
- ## Download Source
190
+ ## Cache Directory
67
191
 
68
- By default the wrapper downloads binaries from the public GitHub release repository configured in `package.json`.
192
+ The downloaded binary is cached here by default:
69
193
 
70
- For internal debugging or private release mirrors, you can override the base URL:
194
+ ```text
195
+ ~/.fastmoss/bin/<version>/<platform>/
196
+ ```
197
+
198
+ Override the cache directory:
71
199
 
72
200
  ```bash
73
- FASTMOSS_DOWNLOAD_BASE_URL=https://downloads.example.com/releases npx @fastmoss/cli
201
+ FASTMOSS_CACHE_DIR=/custom/cache/dir npx @fastmoss/cli
74
202
  ```
75
203
 
204
+ ## Supported Platforms
205
+
206
+ - macOS `amd64`
207
+ - macOS `arm64`
208
+ - Linux `amd64`
209
+ - Linux `arm64`
210
+ - Windows `amd64`
211
+
76
212
  The wrapper will request one of these asset names depending on platform:
77
213
 
78
214
  - `fastmoss-darwin-amd64`
@@ -80,7 +216,3 @@ The wrapper will request one of these asset names depending on platform:
80
216
  - `fastmoss-linux-amd64`
81
217
  - `fastmoss-linux-arm64`
82
218
  - `fastmoss-windows-amd64.exe`
83
-
84
- ## Release Workflow
85
-
86
- The private source repository prepares this package and the matching binaries. The public GitHub release repository then publishes the package and hosts the release assets.
package/README.zh-CN.md ADDED
@@ -0,0 +1,210 @@
1
+ # FastMoss CLI
2
+
3
+ [English](./README.md)
4
+
5
+ FastMoss CLI 用于在终端或 AI Agent 中发现并调用 FastMoss MCP 工具，覆盖 TikTok Shop 选品、达人发现、店铺分析、广告分析、市场洞察、视频/直播分析和 FastMoss 知识库查询等场景。
6
+
7
+ CLI 需要配合 FastMoss CLI Agent Skill 一起使用：
8
+
9
+ - `@fastmoss/cli` 安装 `fastmoss` 命令，用于真正执行工具调用。
10
+ - `npx skills add FastMoss/cli -y -g` 安装 Agent Skill，让你的 Agent 知道有哪些 FastMoss 工具、什么时候使用、怎么调用。
11
+
12
+ Agent 工作流建议两个都安装：
13
+
14
+ ```bash
15
+ npm install -g @fastmoss/cli
16
+ npx skills add FastMoss/cli -y -g
17
+ ```
18
+
19
+ ## 关于 FastMoss
20
+
21
+ [FastMoss](https://www.fastmoss.com/) 是面向全球 TikTok 品牌、商家、服务商、创作者和运营团队的数据分析平台。FastMoss 帮助用户洞察大盘趋势、发现爆品和品类机会、寻找达人与机构、监控竞店、分析广告投放，并研究直播生态。
22
+
23
+ FastMoss 主要提供以 TikTok 和 TikTok Shop 为核心的大数据分析服务，覆盖直播、商品、店铺、达人、广告、视频、音乐、标签等版块，涵盖美国、英国、印尼、越南、菲律宾、泰国、马来西亚、西班牙、墨西哥、法国、德国、巴西等主要 TikTok 商业化国家和区域的数据。
24
+
25
+ ## 安装
26
+
27
+ 不安装，直接通过 npx 运行：
28
+
29
+ ```bash
30
+ npx @fastmoss/cli
31
+ ```
32
+
33
+ 全局安装：
34
+
35
+ ```bash
36
+ npm install -g @fastmoss/cli
37
+ fastmoss
38
+ ```
39
+
40
+ 全局安装后，命令名是 `fastmoss`。如果终端提示 `command not found: fastmoss`，通常是 npm 全局 bin 目录没有加入 `PATH`。
41
+
42
+ 如果你的 npm 配置禁止 lifecycle scripts，可以允许本包的 postinstall 脚本在安装期预下载二进制：
43
+
44
+ ```bash
45
+ npm install -g --allow-scripts=@fastmoss/cli @fastmoss/cli
46
+ ```
47
+
48
+ ## API Key 和积分
49
+
50
+ FastMoss 工具调用需要 API Key，并会消耗积分。访问 [FastMoss 开发者平台](https://developers.fastmoss.com/mcp/overview.html) 登录、创建 MCP API Key、查看用量并管理积分。
51
+
52
+ 常规配置：
53
+
54
+ ```bash
55
+ fastmoss login --api-key <your-api-key>
56
+ fastmoss whoami
57
+ ```
58
+
59
+ 如果积分不足，请在开发者平台的计费/价格页面充值或升级套餐。计费和积分规则见 [FastMoss MCP Pricing](https://developers.fastmoss.com/mcp/pricing.html)。
60
+
61
+ ## 命令
62
+
63
+ 查看版本和帮助：
64
+
65
+ ```bash
66
+ fastmoss --version
67
+ fastmoss help
68
+ ```
69
+
70
+ 登录和本地配置：
71
+
72
+ ```bash
73
+ fastmoss login --api-key <your-api-key>
74
+ fastmoss logout
75
+ fastmoss whoami
76
+ fastmoss set api-key <your-api-key>
77
+ fastmoss clear api-key
78
+ fastmoss set language zh
79
+ fastmoss set language en
80
+ fastmoss show config
81
+ fastmoss show auth
82
+ ```
83
+
84
+ 发现工具：
85
+
86
+ ```bash
87
+ fastmoss tools
88
+ fastmoss tools --json
89
+ fastmoss tools --search <tool_name>
90
+ ```
91
+
92
+ 调用工具：
93
+
94
+ ```bash
95
+ fastmoss call --tool <tool_name> --args '<json>' --output mcp
96
+ fastmoss <tool_name> --args '<json>' --output mcp
97
+ ```
98
+
99
+ LLM 或 Agent 读取结果时优先使用 `--output mcp`。终端里只想看简洁结果时使用 `--output data`。只有调试原始 RPC 响应时才使用 `--output rpc`。
100
+
101
+ 联网命令常用参数：
102
+
103
+ ```bash
104
+ --api-key <api-key>
105
+ --base-url <url>
106
+ --timeout <seconds>
107
+ --insecure-skip-tls
108
+ ```
109
+
110
+ ## 支持的工具
111
+
112
+ 随包发布的 Agent Skill 包含静态工具目录。你也可以执行 `fastmoss tools` 或 `fastmoss tools --json` 查看当前账号实时可用的工具列表。
113
+
114
+ | 分类 | name | title |
115
+ |---|---|---|
116
+ | 广告工具 | `ad_data_overview` | Ad data overview |
117
+ | 广告工具 | `ad_search` | Ad search |
118
+ | 达人工具 | `creator_cargo_summary` | Creator ecommerce summary |
119
+ | 达人工具 | `creator_data_trends` | Creator data trends |
120
+ | 达人工具 | `creator_fans_distribution` | Creator fans distribution |
121
+ | 达人工具 | `creator_product_list` | Creator product list |
122
+ | 达人工具 | `creator_profile_overview` | Creator profile overview |
123
+ | 达人工具 | `creator_rank_top_ecommerce` | Top ecommerce creators |
124
+ | 达人工具 | `creator_rank_top_growth` | Top creator follower growth |
125
+ | 达人工具 | `creator_rank_top_potential` | Top potential creators |
126
+ | 达人工具 | `creator_search` | Creator search |
127
+ | 达人工具 | `creator_video_analysis` | Creator video analysis |
128
+ | 辅助和知识库工具 | `fastmoss_detail_url_examples` | FastMoss Detail URL Examples |
129
+ | 辅助和知识库工具 | `live_detail_analysis` | Live detail analysis and category breakdown |
130
+ | 辅助和知识库工具 | `live_products_list` | Live promoted product list |
131
+ | 辅助和知识库工具 | `live_search` | Live search |
132
+ | 市场洞察工具 | `market_category_analysis` | Category market analysis |
133
+ | 市场洞察工具 | `market_category_author_sales_matrix` | Category creator sales matrix |
134
+ | 市场洞察工具 | `market_category_ranking` | Category market ranking |
135
+ | 商品工具 | `product_category_info` | Product category list |
136
+ | 商品工具 | `product_creator_analysis` | Product creator analysis and creator list |
137
+ | 商品工具 | `product_detail_info` | Product detail info |
138
+ | 商品工具 | `product_investment` | Product ad investment analysis |
139
+ | 商品工具 | `product_overview` | Product overview |
140
+ | 商品工具 | `product_rank_new_listed` | New listed product ranking |
141
+ | 商品工具 | `product_rank_top_selling` | Top selling products |
142
+ | 商品工具 | `product_review_list` | Product review list |
143
+ | 商品工具 | `product_sales_trend` | Product sales trend |
144
+ | 商品工具 | `product_search` | Product search |
145
+ | 商品工具 | `product_sku` | Product SKU analysis |
146
+ | 商品工具 | `product_video_list` | Product video list |
147
+ | 辅助和知识库工具 | `search_category_by_words` | Search TikTok Product Category by Keywords |
148
+ | 辅助和知识库工具 | `search_fastmoss_documents` | FastMoss Knowledge Base Search |
149
+ | 店铺工具 | `shop_base_info` | Shop base info |
150
+ | 店铺工具 | `shop_creator_analysis` | Shop creator analysis and creator list |
151
+ | 店铺工具 | `shop_data_trends` | Shop data trends |
152
+ | 店铺工具 | `shop_investment_analysis` | Shop ad investment analysis |
153
+ | 店铺工具 | `shop_live_analysis` | Shop live analysis and live list |
154
+ | 店铺工具 | `shop_product_analysis` | Shop product analysis and product list |
155
+ | 店铺工具 | `shop_rank_top_selling` | Top selling shops |
156
+ | 店铺工具 | `shop_sale_analysis` | Shop sales analysis |
157
+ | 店铺工具 | `shop_search` | Shop search |
158
+ | 店铺工具 | `shop_video_analysis` | Shop video analysis and video list |
159
+ | 辅助和知识库工具 | `video_data_trends` | Video data trends |
160
+ | 辅助和知识库工具 | `video_detail_analysis` | Video detail analysis and product list |
161
+ | 辅助和知识库工具 | `video_script_info` | Video subtitle script |
162
+ | 辅助和知识库工具 | `video_search` | Video search |
163
+
164
+ ## 二进制下载
165
+
166
+ 本包会安装 `fastmoss` 命令。npm 包本身不内置 Go 二进制文件，而是在安装或首次运行时从 GitHub Releases 下载当前平台对应的 `fastmoss` 二进制，缓存到本地后转发所有 CLI 参数。
167
+
168
+ 安装时会尝试预下载当前平台二进制。如果下载失败，npm 安装仍会完成；首次运行 `fastmoss` 时会再次下载，并显示下载地址。
169
+
170
+ 你可以跳过安装期下载，让首次运行时再下载：
171
+
172
+ ```bash
173
+ FASTMOSS_SKIP_DOWNLOAD=1 npm install -g @fastmoss/cli
174
+ ```
175
+
176
+ 内部调试或私有镜像可以覆盖下载地址：
177
+
178
+ ```bash
179
+ FASTMOSS_DOWNLOAD_BASE_URL=https://downloads.example.com/releases npx @fastmoss/cli
180
+ ```
181
+
182
+ ## 缓存目录
183
+
184
+ 默认缓存目录：
185
+
186
+ ```text
187
+ ~/.fastmoss/bin/<version>/<platform>/
188
+ ```
189
+
190
+ 自定义缓存目录：
191
+
192
+ ```bash
193
+ FASTMOSS_CACHE_DIR=/custom/cache/dir npx @fastmoss/cli
194
+ ```
195
+
196
+ ## 支持平台
197
+
198
+ - macOS `amd64`
199
+ - macOS `arm64`
200
+ - Linux `amd64`
201
+ - Linux `arm64`
202
+ - Windows `amd64`
203
+
204
+ wrapper 会根据当前平台请求以下资产之一：
205
+
206
+ - `fastmoss-darwin-amd64`
207
+ - `fastmoss-darwin-arm64`
208
+ - `fastmoss-linux-amd64`
209
+ - `fastmoss-linux-arm64`
210
+ - `fastmoss-windows-amd64.exe`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fastmoss/cli",
3
- "version": "0.1.1",
3
+ "version": "0.1.3",
4
4
  "description": "FastMoss CLI launcher for npm and npx",
5
5
  "license": "UNLICENSED",
6
6
  "private": false,
@@ -10,7 +10,8 @@
10
10
  "files": [
11
11
  "bin",
12
12
  "lib",
13
- "README.md"
13
+ "README.md",
14
+ "README.zh-CN.md"
14
15
  ],
15
16
  "scripts": {
16
17
  "postinstall": "node ./bin/postinstall.js",