FunnelsGrove CLI

Install:

npm install -g @funnelsgrove/cli
fgrove login

Sync a funnel into its own local folder:

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

Common workflow:

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

Inside a synced folder, fgrove reads .funnelsgrove-sync.json first, so you do not need to run fgrove use when switching between local funnel directories. Use fgrove use only when you want a global fallback context for commands outside a synced folder.

fgrove sync down refuses to overwrite local changes in an existing synced folder. If fgrove sync up says the remote draft changed since your local sync, run fgrove sync rebase: it performs a three-way merge from the recorded base, preserves CLI-managed files, and leaves the working tree untouched when it finds conflicts. Review the merged diff, rerun fgrove validate, then sync up again. sync down --force is the explicit discard path and writes an automatic source backup under .funnelsgrove/rebase-backups/ before replacing hosted paths.

fgrove sync up is for funnels without GitHub source sync. When GitHub is connected, commit and push source changes with normal git, then run fgrove github pull to sync GitHub into the hosted draft. Do not run fgrove sync up for the same local diff.

Use fgrove env pull from a synced folder to refresh only the ignored local .env file after project settings change, without replacing source files. The generated file identifies the current hosted draft through NEXT_PUBLIC_FUNNEL_VERSION_ID, so transactional steps such as email capture work during local QA.

fgrove offer-sets sync reports the applied offer set and written generated files before waiting for GitHub. By default it waits for the exact GitHub sync job. If that job is still pending or running when the wait times out, the command continues with a warning on stderr and asks you to check the eventual result with fgrove github status. Terminal job failures, missing jobs, and API failures still exit non-zero. Pass --no-github-sync to skip the wait entirely when the generated file will be committed through the normal repository workflow.

Create an experiment draft from a strict JSON spec:

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

The spec uses a stable id and type: "step", "paywall", or "pricing" with two to five variants, exactly one control, unique metrics and variant keys, and integer traffic totaling 100. Pricing variants also require offerSetKey and must route to the top-level stepId. See docs/funnelsgrove/recipes/add-experiment.md in a synced funnel for complete valid JSON examples and remediation guidance.

Creation is draft-only: it creates no PostHog flag and activates no traffic. The experiment becomes visible in the UI after the API commits its hosted generated snapshot, and the CLI installs those exact generated bytes locally through recoverable staging. .funnelsgrove-sync.json stays local and ignored.

With --json, success output contains only experimentId, experimentKey, draftVersionId, and writtenPaths, with generated paths in canonical order.

For a non-GitHub funnel, deliver the local source with fgrove sync up. For a GitHub-connected funnel, commit and push the generated source with the rest of the change, then run fgrove github pull; do not commit .funnelsgrove-sync.json or use fgrove sync up for that diff.

GitHub sync workflow:

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

The GitHub commands use the FunnelsGrove API only. fgrove github pull pulls the repository into the hosted draft after you push normal git commits. fgrove publish waits for the current draft to reach GitHub before publishing. If the exact job is still pending or running when that wait times out, publish continues with a warning on stderr and asks you to check the eventual result with fgrove github status. Terminal job failures, missing jobs, and API failures remain fatal. Use --no-github-sync to skip only that CLI pre-publish wait when the hosted draft is already known to match GitHub; the publish worker still performs its normal best-effort post-publish GitHub synchronization. fgrove github push still exists for explicit hosted-draft-to-GitHub recovery work, but it is not the normal path for local source changes. Local .env* files remain CLI-local runtime material from sync down; they are not sent to GitHub sync.

Analytics workflow:

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

Each analytics command accepts --format table|json, --out <path>, --workspace, and --timezone. Use JSON for agents and automations:

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

conversions downloads the one-day conversion totals, primary conversion metrics, full funnel path rows, and step transitions. funnel-path focuses on the ordered path report. transitions focuses on step-by-step advanced/drop-off counts. cohort downloads synced marketing cohort economics for the day. If the requested day has no synced data, or cohort source data is incomplete, the CLI exits non-zero with a human-readable explanation.

The package also keeps the longer funnelsgrove command as a compatibility alias. Use --api-url or FUNNELSGROVE_API_URL for non-production APIs. Use --config or FUNNELSGROVE_CONFIG to keep test credentials separate from the default ~/.funnelsgrove/config.json.