Segmently CLI

First-party command-line interface for Segmently automation.

The CLI is JSON-first and talks to the stable /api/cli/v1/* facade. It does not read Firestore directly and does not call scattered internal product endpoints as its primary contract.

Installation

npm install -g @segmently/cli
segmently --version
segmently auth login

The first public package version is @segmently/[email protected].

One-off execution without a global install:

npm exec --yes --package @segmently/cli -- segmently --version

Production is the default target. Public users do not need to pass an environment flag.

Full installation and update instructions are documented in modules/cli/INSTALLATION.md.

Authentication

segmently auth login
segmently auth status
segmently auth logout

Production is the default environment. Public users do not need to pass --env prod.

For automation, create a scoped project service token and use it through SEGMENTLY_API_KEY.

segmently capabilities

segmently auth token create \
  --project <projectId> \
  --name "CI publish" \
  --scopes projects:read,funnels:read,publish:write \
  --expires-at 2026-06-25T10:00:00.000Z

SEGMENTLY_API_KEY=sgly.prod... segmently publish web --project <projectId> --web-placement <webPlacementId>
segmently auth token list --project <projectId>
segmently auth token revoke <tokenId> --project <projectId>

For read-only launch checks, service tokens can use funnels:read,themes:read,stripe:read,publish:read,analytics:read,domains:read,content-plan:read. Tokens with publish:write also satisfy publish:read; tokens with analytics:write also satisfy analytics:read; tokens with content-plan:write also satisfy content-plan:read. Image upload automation requires assets:write.

The raw service token is returned only once by auth token create. Store it in the CI secret manager, not in the CLI credential file.

Service tokens created by regular project users are short-lived. If --expires-at is omitted, Segmently sets the expiration automatically. The create response includes the exact expiration time.

Service-token scopes are necessary but not sufficient for project operations. Project-scoped product commands are also checked against Billing Access on the server: Web Onboarding commands require web_onboarding.access or a wildcard such as web_onboarding.*, block generation requires web_onboarding.block.regenerate, and Content Plan commands require content_plan.access or content_plan.*. CLI image uploads require cli_assets.upload_image or cli_assets.*.

auth token create, auth token list, and auth token revoke require user auth from browser login. They intentionally do not use SEGMENTLY_API_KEY, because service tokens should not manage other service tokens.

Environments

segmently env list
segmently env current

Production is the public default. env list shows only the public production target.

Shell Completion

segmently completion bash > ~/.local/share/bash-completion/completions/segmently
segmently completion zsh > ~/.zfunc/_segmently
segmently completion fish > ~/.config/fish/completions/segmently.fish

completion is local-only: it does not call the backend and does not require credentials.

Examples

segmently projects list
segmently funnels list --project <projectId>
segmently funnels versions <funnelId> --project <projectId>
segmently funnels export <funnelId> <versionId> --project <projectId> --output flow.json
segmently funnels audit <funnelId> <versionId> --project <projectId> --required-variable goal,name,email --require-paywall
segmently funnels diff --project <projectId> --source-funnel <funnelId> --source-version <versionId> --target-funnel <funnelId> --target-version <versionId> --explain
segmently funnels graph dry-run --project <projectId> --funnel <funnelId> --version-id <versionId> --file graph.json
segmently funnels graph apply --project <projectId> --funnel <funnelId> --version-id <versionId> --file graph.json
segmently funnels screens apply --project <projectId> --funnel <funnelId> --version-id <versionId> --file screens.json
segmently funnels variables apply --project <projectId> --funnel <funnelId> --version-id <versionId> --file variables.json --dry-run
segmently funnels edges apply --project <projectId> --funnel <funnelId> --version-id <versionId> --file edges.json
segmently funnels conditions apply --project <projectId> --funnel <funnelId> --version-id <versionId> --file conditions.json
segmently stripe products --project <projectId> --mode test
segmently launch preflight --project <projectId> --funnel <funnelId> --version-id <versionId> --web-placement <webPlacementId> --required-variable goal,name,email --require-paywall --require-stripe-sandbox
segmently analytics settings get --project <projectId>
segmently analytics settings apply --project <projectId> --file analytics-settings.json --merge
segmently analytics probe --project <projectId> --required-platform facebook_pixel,facebook_capi --required-url-param fbclid,utm_source,utm_medium,utm_campaign --require-client-side --require-server-side
segmently domains status --project <projectId>
segmently domains verify --project <projectId>
segmently assets upload-image ./hero.png --project <projectId> --raw-url
segmently assets upload-image ./hero.png --project <projectId> --asset
segmently assets upload-image ./hero.png --project <projectId> --folder onboarding/reference
segmently content-plan strategies list --project <projectId> --include-counts
segmently content-plan strategies export <strategyId> --project <projectId> --include-posts --output content-plan-strategy.json
segmently content-plan strategies audit <strategyId> --project <projectId> --required-platform linkedin,x --require-generated-posts
segmently content-plan profile export --project <projectId> --author <authorId> --platform linkedin,x --output creator-profile.json
segmently content-plan profile apply --project <projectId> --file creator-profile.json --dry-run
segmently content-plan pillars apply --project <projectId> --author <authorId> --file pillars.json --dry-run
segmently content-plan post-templates apply linkedin --project <projectId> --author <authorId> --file linkedin-templates.json --dry-run
segmently fixtures launch seed --project <projectId> --alias-prefix qa-launch --name "QA Launch" --dry-run
segmently support evidence from-run --file run-artifact.json --output evidence.md
segmently generate block --project <projectId> --file request.json
segmently tasks get <taskId> --project <projectId>
segmently publish web --project <projectId> --web-placement <webPlacementId>
segmently publish web --project <projectId> --funnel <funnelId> --version <versionId> --alias <alias>
segmently publish verify --project <projectId> --url /ab-launch --public-base-url https://api.segmently.ai --query-param fbclid=fb-test,utm_source=facebook --required-variant control,treatment
segmently ab-tests list --project <projectId> --status published --tag copy-test --baseline-variant control --iteration iter-2026-05
segmently ab-tests publications <abTestId> --project <projectId> --tag copy-test --baseline-variant control --iteration iter-2026-05

assets upload-image calls the CLI facade route /api/cli/v1/projects/:projectId/assets/upload/image, which reuses the existing Builder Assets upload and resize pipeline. By default, uploaded files are stored under projects/<projectId>/cli-assets/images/.... The normal JSON response includes the original URL, the small URL, the full legacy assetUrl variants, and the V2 asset shape { "original": "...", "small": "..." }.

The command requires assets:write on service tokens plus project Billing Access capability cli_assets.upload_image.