# @funnelsgrove/cli 中文文档

规范地址：https://npmcn.com/package/%40funnelsgrove/cli/

版本：0\.1\.379
npm 元数据更新时间：2026-11-14T01:16:30.610Z
中文译文更新时间：2026-11-15T18:14:31.956Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40funnelsgrove/cli
原文对照：https://npmcn.com/package/%40funnelsgrove/cli/?lang=original
项目主页：https://github.com/The-Solid-Grove/funnelsgrove#readme
源码仓库：https://github.com/The-Solid-Grove/funnelsgrove

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2 MB，256 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：4 个
- 首次发布：2026-05-09T21:30:52.724Z
- 最新版本发布：2026-11-14T01:16:30.413Z
- 近 30 天下载量：12883（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：227（近 12 个月 227 个）

## 中文简介

用于编辑、同步和发布漏斗的漏斗Grove命令行工具

## 安装

```sh
npm install @funnelsgrove/cli
```

也可以使用：`pnpm add @funnelsgrove/cli`、`yarn add @funnelsgrove/cli`、`bun add @funnelsgrove/cli`

## README

# 漏斗格罗夫CLI

安装 :

```bash
npm install -g @funnelsgrove/cli
fgrove login
```

更新可见于 `PATH` (包括单独的NVM和 Homebrew 前缀),有一个命令:

```bash
fgrove update
```

使用 `fgrove update --dry-run` 首先检查设施。 更新器 运行每个安装的兄弟姐妹 `npm`,因此无法复制全局安装 沉默地留在不同的CLI版本上.

从三个启动模板中创建一个新的主机漏斗 :

```bash
fgrove whoami
fgrove projects list
fgrove templates list
fgrove templates show one-page-v2
fgrove funnels create --project fitness --template one-page-v2 --name FitBee --idempotency-key <creation-key> --json
fgrove sync down --funnel <returned-funnel-id> --dir ./fitbee
```

模板卡包括描述、适当的行程、包括屏幕和 创建命令. `--json` 用于列表和显示。 发现者读取 通过连接的账户提供官方目录,保留其名称, 键和被绑定的演示/源版本;检查当前行程的演示. 主机创建需要已有的项目; 通过 `--workspace` 当选择不同的工作空间时。 模板 sattle 匹配应用程序 : `default`, (中文(简体) ), `one-page`,以及 `one-page-v2`。 。 。 .

`funnels create` 使用与应用程序相同的API设置工作流程. 它等待着一个 可下载草稿,而自动初始预览则单独构建. `--timeout` 默认为120秒。 进展和恢复身份进入标准; stdout包含一个分页创建行,或一个结果对象带有 `--json`。 。 。 . 如果请求的结果不确定,则保留创建密钥并重新使用. A 类 等待超时不取消或删除主机漏斗。 下载返回的 标识与 `sync down`· ; `funnels clone` 而不是复制现有的漏斗.

下载后,确定产品/观众/报价/品牌简介和根 `Design.md` 在定制之前。 费斯克 `create-funnel` 技术拥有这个 输入工作流程;启动艺术品、证明和法律/报价副本需要修改. 启动者预览仅包含在同步并发布后本地化的后期修改.

在公共漏斗屏幕库中查找没有账户的可视示例 :

```bash
fgrove references projects --category 'Self-growth / book summaries'
fgrove references project headway
fgrove references ads --project headway --format social-media-mockup --angle problem_agitation --limit 20
fgrove references ads --before <cursor> --json
fgrove references categories
fgrove references list --category 'Health Fitness' --step-type single-choice
fgrove references show <funnel-id> --json
fgrove references steps <funnel-id>
fgrove references step <funnel-id> <screen-id-or-position> --json
```

`projects` 列出产品及其顶级广告; `project` 显示一个产品及其 有文本、日期和媒体链接的广告. `ads` 支持准确的项目,类别, 格式和角度过滤器。 它的极限是1到100的整数;使用 已返回 `nextBefore` 值为 `--before` 以读取下一页.

`show` 返回完整记录的行程; `steps` 给定密钥命令 概要; `step` 返回带有图像链接、可见文本、按钮和 选项标签,并在可用时作简短的可视化描述。 开始位置 1. 每个命令支持 `--json` 财务报告和审定财务报表 `--site-url` (默认 : `https://www.funnelsgrove.com`) (中文(简体) ). 这些命令使用公共参考服务 独立于您的账户 API,而不更改活动漏斗。 内容 是带有不确定性注释的自动观察;检查之前的实际图像 调整设计 无法获取的观测数据有明确标记.

将漏斗同步到本地文件夹 :

```bash
fgrove sync down --funnel claimbee-ios --dir ./claimbee-ios
cd ./claimbee-ios
```

共同工作流程:

```bash
fgrove status
git status --short
fgrove github status
fgrove docs
# if GitHub is connected: git push, then fgrove github pull
# if GitHub is not connected:
fgrove sync up --message 'Update funnel copy'
fgrove publish --env preview
```

在一个同步的文件夹里, `fgrove` 读取 `.funnelsgrove-sync.json` 首先,所以你不需要运行 `fgrove use` 当切换本地漏斗目录时。 使用 `fgrove use` 仅在您想要同步文件夹外命令的全局倒置上下文时.

`fgrove funnels clone` 复制草稿和漏斗的报价集映射。 这个 克隆重用相同的项目级别报价集和付款配置;自定义域名 不将配置复制到新预览中.

`fgrove sync down` 拒绝覆盖已同步的本地更改 文件夹. `fgrove sync up` 只在一个原子中发送已更改并删除的路径 草稿补丁。 它排除了与文件夹根匹配的路径 `.gitignore` 财务报告和审定财务报表 总是这样 `.claude/settings.local.json` 本地, 允许共享文件 例如 `.claude/settings.json`。同步编辑的不同步自动重置;如果相同 路径远程更改, 运行 `fgrove sync rebase`: 它进行三向合并 保存 CLI 管理的文件,并离开工作树 当它发现冲突时,没有受到影响。 审查合并的 diff, 重新运行 `fgrove validate`,然后再次同步. `sync down --force` 是明确的丢弃路径并写入自动源 备份在 `.funnelsgrove/rebase-backups/` 在替换主机路径之前.

下面更改的图像 `public/` 直接上传到资产存储中,然后 原子补丁中包含了小的不可变资产引用. 同步重试 使用决定性的可耐用性编码键,所以失去的响应无法创建 第二稿文本。 CLI 自动返回候选人同步 兼容的 API 缺少快速程序或更改集超过 补丁限制 .

`fgrove sync up` 用于没有 GitHub 源代码同步的漏斗。 当 GitHub 时 连接、 承诺和推动源更改与普通 git, 然后运行 `fgrove github pull` 将 GitHub 同步到主机草稿。 不运行 `fgrove sync up` 同一个本地diff.

使用 `fgrove env pull` 从同步文件夹中仅刷新被忽略的本地 `.env` 在项目设置更改后,不替换源文件。 生成的文件通过 `NEXT_PUBLIC_FUNNEL_VERSION_ID`,所以在本地QA期间,电子邮件抓取工作等交易步骤.

提供集和支付映射是运行时间配置. 它们被远程解决,以供预览和发布漏斗; `sync down` 不生成或下载要约集源文件.

从严格的 JSON 规格创建实验草稿 :

```bash
fgrove experiments create --spec experiment.json --dir .
fgrove experiments create --spec experiment.json --dir . --json
fgrove experiments start <experiment-uuid>
fgrove experiments stop <experiment-uuid>
fgrove experiments restart <experiment-uuid> --json
fgrove validate
```

光谱使用稳定 `id` 财务报告和审定财务报表 `type: "step"`, (中文(简体) ), `"paywall"`,或 `"pricing"` 有2到5个变体,完全是一个控制,独特的度量和变体键,整数流量总计为100. 定价变体也需要 `offerSetKey` 并必须路径到顶层 `stepId`。见 `docs/funnelsgrove/recipes/add-experiment.md` 用于完整有效的 JSON 示例和补救指导的同步漏斗.

创建仅是草稿:它不创建PostHog旗并启动任何流量. 该实验在API承担其主机生成的快照后在UI中可见,而CLI通过可回收的中转在当地安装这些精确生成的字节. `.funnelsgrove-sync.json` 留在本地并忽略.

与 `--json`,成功输出仅包含 `experimentId`, (中文(简体) ), `experimentKey`, (中文(简体) ), `draftVersionId`,以及 `writtenPaths`,以条条顺序生成的路径.

对于非吉特Hub漏斗,用 `fgrove sync up`。对于一个连接了 GitHub 的漏斗,将生成的源与其余变化一起承诺并推进,然后运行 `fgrove github pull`; 不执行 `.funnelsgrove-sync.json` 或用途 `fgrove sync up` 为了那个diff.

GitHub 同步工作流程 :

```bash
fgrove github status --funnel claimbee-general
fgrove github connect --funnel claimbee-general --account The-Solid-Grove --repo claimbee-funnel
git push
fgrove github pull --funnel claimbee-general
fgrove publish --funnel claimbee-general --env preview
```

GitHub 命令只使用 FunnelsGrove API. `fgrove github pull` 牵引 在您将正常 git 输入后, 存储器会输入主机草稿 . `fgrove publish` 等待当前草稿在发布前到达 GitHub . 它会写验证, GitHub 同步, 队列, 构建, 图像优化, 以及上传 正在向 stderr 推进,同时将最后的 URL/版本行单独保存在 stdout 上. 如果确切的工作仍未完成或等待时间已过时仍在运行,请公布 在 stderr 上继续警告,并请您检查最终结果 与 `fgrove github status`。终端工作失败、缺少工作和API 失败仍然是致命的。 使用 `--no-github-sync` 只跳过 CLI 预显示 等待主机草稿已经与 GitHub 匹配; 出版人员 仍能实现正常最优后GitHub同步. `fgrove github push` 仍然存在明确的主机草稿到GitHub回收 工作,但这不是本地源变化的正常路径。 当地 `.env*` 文档仍然是 CLI 本地运行时间材料 `sync down`;没有发送到 GitHub 同步 .

分析工作流程:

```bash
fgrove analytics conversions --project claimbee --funnel claimbee-ios --date 2026-06-11
fgrove analytics funnel-path --project claimbee --funnel claimbee-ios --date 2026-06-11
fgrove analytics transitions --project claimbee --funnel claimbee-ios --date 2026-06-11
fgrove analytics cohort --project claimbee --date 2026-06-11
```

每个分析命令接受 `--format table|json`, (中文(简体) ), `--out <path>`, (中文(简体) ), `--workspace`,以及 `--timezone`将JSON用于代理和自动化:

```bash
fgrove analytics conversions --project claimbee --funnel claimbee-ios --date 2026-06-11 --format json --out conversions.json
```

`conversions` 下载转换总量,一级转换度量衡,全漏斗路径行,和步态过渡. `funnel-path` 专注于命令路径报告. `transitions` 注重分步进取/倒计时. `cohort` 下载当天同步的营销组经济. 其年度预测使用与Cohort Marketing和每日报告相同的被节省距离中点. 缺失的有效预测范围产生无效的JSON值和空表单元格;遗留模型点从来不是倒数. 项目必须启用Cohort Marketing。 如果请求的期间没有同步数据,或组源数据不完整,则CLI会用人可读的解释退出非0.

`conversions`, (中文(简体) ), `funnel-path`,以及 `transitions` 报告日期 `--date`区域 `--from` 财务报告和审定财务报表 `--to` (含,全范围合计). 它们使用所有已发布的有流量的漏斗版本中选定的日期范围. `funnel-path` 财务报告和审定财务报表 `transitions` 遵循当前已发布的流程顺序。 与当前流量相去不远的选定周期流量相去相去的步数,出现在“当前漏斗中不存在”;JSON行标注这些步数 `section: "not-in-current-funnel"`。 。 。 .

```bash
fgrove analytics transitions --project claimbee --funnel claimbee-ios --from 2026-06-01 --to 2026-06-14
```

包裹也保持了更长的时间 `funnelsgrove` 命令作为相容性别名.

从终端跟踪项目设置指南. 步骤、指示和 检查与控制台指南相同,因此一个编码代理可以通过它:

```bash
fgrove use --project claimbee
fgrove setup                      # every step, its readiness, what is missing, next step
fgrove setup --json               # the same for agents
fgrove setup docs stripe_setup    # full instructions for one step
fgrove setup check stripe_setup   # confirm the live webhook with Stripe
fgrove setup check meta_pixel --test-event-code TEST12345
fgrove setup complete legal_support
fgrove setup meta-traffic off     # the project does not buy Meta traffic
fgrove setup secrets stripe-test  # single-use link to a FunnelsGrove form for Stripe keys
```

特工们从不拿走花纹钥匙或Meta访问令牌. `fgrove setup secrets <stripe-test|stripe-live|meta>` 打印一次工作30分钟的链接 打开它的人以漏斗格罗夫形式输入值.

Frade, Province Sets, 域名, Meta 和 app- access 索赔是准备状态 检查:只有观察到的证据才能完成,而且 `setup complete` 没有. 最后一步,自定义漏斗,可以跳过 `setup complete customize_funnel`。 。 。 .

运行 `fgrove setup` 标注其连接CLI步骤. `check`, (中文(简体) ), `meta-traffic` 财务报告和审定财务报表 `secrets` 需要工作空间管理员的作用,例如 匹配控制台按钮;状态、文件和完成标记需要成员.

通过本地 JSON 文件编辑盈利成本 :

```bash
fgrove expenses pull --project claimbee --file expenses.json
# edit expenses.json; omit id and updatedAt for new expenses
fgrove expenses publish --project claimbee --file expenses.json
```

出版创建新行并更新文件中已经存在的行. 从来没有 删除文件中没有的远程开支, 并拒绝覆盖 从上次拉起就换了行 再次拉来解决同步编辑问题 .

编辑提供 设相同相. 对于折扣的入门价格和两阶段的折扣, ưμ㼯a `docs/guides/edit-offer-sets.md`数字 :

```bash
fgrove offer-sets pull --project claimbee            # writes offer-sets.json
fgrove offer-sets prices --project claimbee --env live
# edit offer-sets.json; for a new set omit id/updatedAt, keep paymentProfileId
fgrove offer-sets publish --project claimbee --dry-run
fgrove offer-sets publish --project claimbee
```

只发送了已更改的设定 。 设定 `isActive` 改为 `false` 以归档集,其中 当漏斗、路由、域或实验仍在使用时,失败。 没有设置 从文件开始从不删除,自此之后,出版拒绝更改套件 最后的拉动。 项目 `paymentProfileBindings` (例如,PayPal绑定)不是 在文件中; 保留了已有的, 并从另一个起始处复制了新集 没有他们.

读取收费提醒并预防交易历史搜索一个 UTC月 没有客户或卡片数据 :

```bash
fgrove alerts list --project claimbee --month 2026-10          # every alert: ids, dates, service, amount, status, outcome
fgrove alerts stats --project claimbee --month 2026-10 --json  # counts by service, refund/cancellation shares, FunnelsGrove cost
fgrove prevent list --project claimbee --month 2026-10         # every transaction search / inquiry: date, program, outcome, amount, scheme, status
fgrove prevent stats --project claimbee --month 2026-10        # searches, found rate, Prevent deflection rate
```

`--month` 默认为当月。 列出命令下载每个页面 在打印之前。 结果是 `refunded automatically`, (中文(简体) ), `refunded manually`, (中文(简体) ), `needs review / pending`, (中文(简体) ), `closed without refund` 或者说 `informational`,加上 订阅取消状态;百分比 `alerts stats` 全部份额 当月收到警报。 商机警报被计数,但直接计费 由Merchanto;成本线路覆盖了FunnelsGrove对于整个工程的提示. 产出从来不包括客户邮件,姓名,电话号码,IP地址, 卡片数字、网络引用或条纹标识符.

支持用户( 仅工作空间管理员): 找到属于的项目, 通过电子邮件或漏斗用户身份查找, 退还所选的付款并取消 它们的订阅:

```bash
fgrove users find --email buyer@example.com --json   # every project you administer where this user exists, each with its lookup
fgrove users lookup --project claimbee --email buyer@example.com --json   # users, live subscriptions, payments with refund eligibility
fgrove users refund --project claimbee --email buyer@example.com --payment ch_123 --payment pay_456 --dry-run
fgrove users refund --project claimbee --email buyer@example.com --payment ch_123 --payment pay_456
fgrove users cancel --project claimbee --user-id 8f1c2d   # at period end; --now cancels immediately without refunding the remainder
```

`customers` 仍为 `users`准确通过其中之一 `--email` 或者说 `--user-id`· ; `--env test` 读取测试模式 用户. `find` 搜索您所属的每个工作区( 以 `--workspace`),将您不是管理员的工作空间列表为未搜索 无法搜索工程时退出 1 。 Frede 收费和订阅来自 Frede; Solidgate 付款来自FunnelsGrove分类账,退款从 坚固门. PayPal的订阅和销售均取自状况为 从PayPal直播;退款来自分类账,销售PayPal显示 不同方式的退款,在记录退款的 webhook 之前,不得退款. 退款是每笔付款剩余数额的全额退款,使用 由 `lookup` (PayPal销售身份证为印出,无 前缀). 有争议的付款不得退还。 每笔钱最多退一次, (c) 包括防止收费退还同一款项。 A 类 仍在处理中的固态门或PayPal退款报告为 `processing`; 运行 `lookup` 待会再确认 如果任何付款失败, 命令退出 1 . `cancel` 拒绝猜测何时数 订阅仍在计费;通过 `--subscription`。付费直播 仅在期末取消订阅; `--now` 为 PayPal 在 `--env test`时 `lookup` 报告a 没有回答的提供者,缺少数据并不意味着没有 订阅.

向漏斗格罗夫团队报告一个错误 :

```bash
fgrove bug report "publish hangs at image optimization" --log ./publish.log --dry-run   # show what would be sent
fgrove bug report "publish hangs at image optimization" --log ./publish.log
```

报告载有您的信息、CLI版本、节点版本和平台,以及 来自本地同步的工作空间和漏斗显示于 `--dir` (或 选择工作空间、工程和漏斗 `fgrove use`) (中文(简体) ). `--log` 附上 日志文件的最后两万个字符为 - is, 所以首先删除机密 。 这个 命令打印已存档报表的引用.

使用 `--api-url` 或者说 `FUNNELSGROVE_API_URL` 非生产的API. 使用 `--config` 或者说 `FUNNELSGROVE_CONFIG` 将测试证书与默认证书分开 `~/.funnelsgrove/config.json`。 。 。 .

### 添加内容区域

运行 `fgrove locales add ru --dir ./my-funnel` 复制每个默认内容 对象进入 `src/localization/ru/`,保留其路径相对于 `src/`。 。 。 . 原始内容保持原地;已翻译文件导入其结构类型. 重复运行保存翻译,添加缺失的出口和修复注册. 翻译新内容, 运行 `npx tsc --noEmit`,审查 `?locale=ru` 预览语言 选择器,然后通过正常的工作流程同步并发布。 运行 `fgrove docs` 完全本地化指南。 漏斗必须使用运行时发布支持 URL 区域选择; 此命令不会升级依赖性 .

### 新项目和花旗报价

```bash
fgrove projects create --name Canary --reuse-existing --json
fgrove offer-sets create --project canary --key intro --name "Intro offer" --plan weekly=11.99/week --plan monthly=24.99/month --plan yearly=79.99/year --discount 50 --default-plan monthly --featured monthly="Most popular" --env test --assign-funnel canary --dry-run
fgrove offer-sets assign --project canary --funnel canary --offer-set intro
```

检查干线,然后删除 `--dry-run` 创建。 纸质证书保留 服务器。 价格按规定的正常数额延长; `--discount 50` 收费 首期减少50%(初始报价),并显示全部价格. 重复同样的密钥 `--env live` 填充 Live 映射。 使用 `--payment-profile` 当存在多个花纹配置文件时。 指定替换所有当前漏斗集; `--default` 选择重复的 `--offer-set` 数值。 分别发相. 见 `docs/product-specs/cli-funnel-editing.md` (CLI-BR-008-010,CLI-SC-027-035).

## 常见问题

### @funnelsgrove/cli 是什么？

用于编辑、同步和发布漏斗的漏斗Grove命令行工具

### 如何安装 @funnelsgrove/cli？

在项目目录运行 npm install @funnelsgrove/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 fgrove、funnelsgrove，可以用 npx fgrove 直接运行。

### @funnelsgrove/cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/funnelsgrove\_\_cli 是否存在。

### @funnelsgrove/cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @funnelsgrove/cli 可以商用吗？

@funnelsgrove/cli 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @funnelsgrove/cli 的下载量有多少？

根据 npm 官方下载统计，@funnelsgrove/cli 在 2026/10/16 – 2026/11/14 这 30 天内被下载 12,883 次，日均约 429 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @funnelsgrove/cli 还在维护吗？

最新版本 0\.1\.379 发布于 2026/11/14（1 天前）；至今共发布 227 个版本，其中过去 12 个月发布了 227 个；首次发布于 2026/05/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。