/segmently-cli-guide

Segmently CLI Command Map

Use this file to choose customer-safe command families, scopes, and follow-up checks for the installed production CLI.

Authentication

For automation, use a service token with the smallest required scopes. Store it outside the repository, for example in your CI system's encrypted secret store. Never paste token values into chat, docs, or issue trackers.

Subscription Access

CLI project operations require two independent permissions:

• CLI auth/scope: a signed-in user or service token with the command scope.
• Product subscription: the project must have the product entitlement required by the command family.

Service-token scopes do not grant subscription access. If a command returns a payment/subscription error, confirm that the project has the required product subscription before changing token scopes.

Structured 402 payment_required responses with reason: missing_capability identify the missing project feature in requiredCapability (for example product_analysis.access or web_onboarding.access). Treat this as a project access blocker, not an authentication or token-scope problem.

Core Read And Audit

Project Lookup Pattern

When the user names a project, first run segmently projects list and match against id, name, and projectName. projectName is the UI card title, so it may differ from the canonical name. If the user gives a project ID, confirm with segmently projects get <projectId> before running scoped commands. When names are ambiguous, use secondary clues from list/get output such as description, created/updated dates, platform, or role, then ask for confirmation.

Funnel Version And Export Pattern

Use funnels get to read the funnel summary and latestVersionId, then use that version id for screens, audit, or export:

segmently funnels get <funnelId> <projectId>
segmently funnels versions <funnelId> <projectId>
segmently funnels export <funnelId> <versionId> <projectId> --output flow.json

funnels export takes versionId as a positional argument. Do not use --version-id with funnels export. Without --output, export writes the full envelope (funnel, version, and flowDocument) to stdout; with --output, it writes only the canonical FlowDocument JSON to the file and prints a short summary.

If funnels versions is empty on an older backend but funnels get returns a latestVersionId, use that latestVersionId directly for read-only commands and report the version-list issue. Versions without updatedAt may be readable by id even when an older list endpoint omits them.

Write And Publish

Screen-Level Atomic Operations

Use these operations as composable building blocks. They are safer than applying a full funnel manifest when the task is scoped to existing V2 StepNode screens.

Operational Surfaces

Canonical Published URL

publish web, web-placements publish, and web-placements list can return a path (webUrl / publishedUrl) rather than a fully qualified URL. Build the customer-facing URL from authoritative reads:

segmently domains status --project <projectId>
segmently web-placements list --project <projectId>
segmently publish verify --project <projectId> --url <publishedUrl> --public-base-url https://<canonical-domain>

Use the active custom domain from domains status when hasDomain=true and status=active; otherwise use appUrl from segmently env current. Never infer the canonical host by probing api.segmently.ai or app.segmently.ai.

Product Page

Product Page commands are available for approved workflows. Detailed Product entity mutation payloads are intentionally omitted from this public guide.

Content Plan

Content Plan apply commands upsert explicit manifests; accept promotes generated drafts; set-current activates an existing author/design resource. Generated draft lookup uses --generation, not the removed --task option.

For detailed Content Plan workflows, manifests, design-reference variants, and text-budget rules, use segmently-cli-content-plan-guide. This general guide keeps only the command map.