/segmently-cli-content-plan-guide

Content Plan CLI Commands

Use this file for command and scope lookup.

Authentication And Access

Content Plan commands require Content Plan subscription access in addition to CLI scopes. content-plan:write satisfies read.

CLI 1.0.0 Flow Entry

Use doctor before assembling a full flow by hand. It reads the same readiness predicates as the Content Plan wizard and reports the exact next command for the first missing required step.

Canonical 1.0.0 verbs: apply = manifest upsert, accept = promote a generated draft, set-current = activate, delete = delete a document, and remove = remove list membership. Generated-draft filters use --generation, never the removed --task option.

Full Project Bootstrap

Use these when an empty or partially configured project must be prepared for a manual demo or reviewer flow from a local manifest. The bootstrap command is an orchestrator over atomic CLI APIs; use the atomic commands below when only one resource needs to change.

bootstrap apply validates the manifest and the referenced system_platforms catalog before any mutating request. --skip-validation bypasses only the manifest validator; it never bypasses the platform preflight.

Authors

Use these first when the author ID is unknown.

Author Platforms And Voice

Use platform commands to seed the Content Plan tabs and publishing platforms before creating strategies or calendar posts.

AI Models

Content Plan CLI model preferences are resolved from project-scoped user keys only. The current CLI surface exposes Google models for post generation and image generation; it does not use fallback keys outside the configured project user scope.

Articles / Flexible Layout Drafts

Strategies

Cadence And Calendar Publications

Use these when a strategy exists and the operator needs deterministic Calendar slots or cadence edits.

Official X Research And Listening

All X operations are explicit and budget-gated. --dry-run validates bounds, connection, feature gates, and project policy while making zero X requests. Before using this table, run segmently capabilities and confirm it advertises both the content-plan x ... family and the engagement/publication X delivery family. A documented command is not available when the selected backend or installed CLI does not expose it.

X Human Review, Manual Delivery, And Analytics

Approval never sends. A non-dry create requires the exact confirmation string returned by approval/dry-run. needs_reconciliation blocks another send. Reply estimates/results include a separate source-post read as sourceCheckUsage and aggregate that cost with the create.

Provider error meaning is stable: 401 requires reconnect; 403 is x_provider_forbidden (usually app/project entitlement) and must not be presented as a disconnected account. Analytics 403 creates no snapshot.

Topics And Aspects

ContentTopic.postBreakdown[] is the topic-aspect list. Aspects are not standalone documents.

Research Runs

Research runs are one document under research_runs/{runId} with inline brief, research, and analysis phase fields. Launch commands return a runId, not a backend taskId; inspect status with research get/list.

Post Generation

posts generate can be flag-driven for one topic/aspect/platform cell or manifest-driven with --file for the full generate-posts contract. Launch commands return a backend taskId; always inspect the task before assuming the workflow finished.

Post Command Groups

Use these groups when planning a full post QA run. The operator can execute the groups one by one; the CLI does not need one giant command for the whole flow.

Known gap: true full post regeneration from only an existing post ID still depends on stored generation context. Track it in references/backlog.md.

Post Asset Slots

Use these when a post already exists and the operator wants to repair or regenerate only its visual asset plan or one image slot. Always run posts resolve first if the post ID may be a generated draft instead of a canonical content_posts document.

Slot generation accepts --negative-prompt, --provider, --quality, --openai-size, --aspect-ratio, --image-size, --style, repeatable --reference-image, and --reference-images-file. When these options are omitted, slots generate inherits the rich prompt package from the selected slot experiment, falling back to the first experiment that has prompt metadata. This includes aspectRatio, imageSize, quality, provider, model, and reference images. Use explicit flags only to override the stored package for an eval. Use --source-experiment-id <id> to inherit from a specific experiment. Use --no-inherit-slot-package only for fully manual eval payloads where all prompt, model, aspect, and reference fields are provided explicitly.

Backend Tasks

Use these after any command that returns taskId, including topic aspect AI generation, post generation, post asset planning/regeneration, and slot image generation. Research launch commands return runId instead, so inspect them with content-plan research wait/get/list.

tasks get intentionally returns the task document summary and phase data but does not expand internal prompt bundles, private model call payloads, or hidden reference downloads. For customer troubleshooting, combine tasks get with the public artifact read that matches the workflow, such as content-plan posts drafts list --generation <generationId> --include-slots, content-plan posts resolve, or content-plan posts assets slots list|get. If that is not enough, explain that the remaining evidence requires Segmently support/operator diagnostics.

For posts generate --apply-mode draft_review, generated post artifacts may be stored under post_generations/{taskId}/generatedPosts and referenced from task.result.artifacts[] before they are applied as canonical content_posts. Use content-plan posts drafts list --generation <generationId> --include-slots to inspect those drafts directly.

Task outcome is part of the command contract:

• with --wait, failed, cancelled, or timed-out tasks exit non-zero while retaining task/result evidence on stdout;
• without --wait, a launch that returns taskId also reports taskState: "pending" and a copyable followUp command;
• run the followUp or segmently tasks get <taskId> --project <projectId> before claiming that generation completed.

Post generation flags map to the existing agent contract:

• --scope topic|sprint|strategy
• --topic, --strategy, --sprint, --publication
• --platform, --posts-per-platform, --as-series, --series-count, --series-flavor
• --apply-mode draft_review|auto_apply_topic|auto_apply_sprint
• --asset-mode text_only|plan_only|plan_and_generate
• --planning-mode auto|manual
• --cell-mode single|variants|series|fresh-variants, --aspect-key, --method cope|direct, --template-id, --template-ids, --format-id, --asset-intent, --length-bucket, --fresh-variants-count
• --research-selection researchSelectionByTopic.json
• --wait, --poll-interval-ms, --timeout-ms for immediate task polling

Creator Profile, Pillars, And Templates

Content Themes

Use deterministic theme commands for bootstrap/demo setup. Use AI generation only when the user wants generated theme candidates before applying them.

Design Profiles

Design profile apply accepts flat design-system JSON, skill composite JSON, or a CLI transfer manifest.

Full Design-System Packages

Use packages when one visual foundation spans multiple platform formats/profile keys. Use the narrower designs family only for one profile variant.

Assets For Design References

Asset upload is not a Content Plan write. Uploaded images appear in Design only after their URLs are included in visualReferences and applied with content-plan designs apply.