CLI Reference

Every supported UniPost CLI command, grouped by workflow, with compact examples for agents and CI.

Examples use --json whenever structured output is available so the response shape is deterministic. The CLI still keeps human-readable output as the normal terminal default.

Global flags

Flag	Use
`--json`	Alias for `--output json`; prints the stable envelope used by agents and CI.
`--output <table\|json\|yaml>`	Selects human/table, JSON, or YAML output where the command supports structured output.
`--field <field>`	Prints one field from the JSON envelope, useful for scripts.
`--base-url <url>`	Overrides the API origin for this run.
`--api-key <key>`	Uses an API key for this run. With `auth login` or `init`, it can create the local CLI binding.
`--setup-token <token>`	Uses a short-lived Dashboard setup token for local CLI onboarding.
`--metadata-only`	Records redacted API-key metadata only; authenticated commands still need `UNIPOST_API_KEY` or `--api-key`.
`--profile <id>` / `--account <id>`	Selects a profile or account for commands that need one.
`--limit`, `--cursor`, `--all`	Controls pagination for list commands.
`--yes`	Confirms local auth replacement, publish-capable writes, or destructive actions after user approval.
`--replace-key` / `--reauth`	Intentionally replaces or refreshes the single local CLI auth binding instead of reusing a valid one.
`--idempotency-key <key>`	Required for publish-capable writes after approval.

Setup & Diagnostics

Initialize local config, create the first usable workspace context, and inspect runtime readiness.

SETUPinitunipost init --json

Checks auth, loads workspace/profile context, and writes safe local defaults when possible.

Example response

SETUPquickstartunipost quickstart --name "Studio" --json

Guides the next setup step by summarizing workspace, profile, account, and draft readiness.

Example response

SETUPdoctorunipost doctor --json

Runs CLI, API reachability, auth, workspace, and telemetry diagnostics.

Example response

Auth & Config

AUTHauth login --setup-tokenunipost auth login --setup-token ust_... --client terminal --base-url https://api.unipost.dev --json

Exchanges a short-lived Dashboard setup token for a named local CLI credential. If a valid local binding already exists, the CLI returns `already_configured` and does not consume the token unless you pass `--replace-key`, `--reauth`, or `--yes`.

Example response

AUTHauth login --api-keyunipost auth login --api-key up_live_... --json

Validates an existing API key and stores a secure local CLI credential when available. If a local binding already exists, add `--yes` after confirming replacement.

Example response

AUTHauth logoutunipost auth logout --json

Clears the single local UniPost CLI credential and stored base URL.

Example response

AUTHauth statusunipost auth status --json

Reports local auth state and verifies a usable credential when present.

Example response

AUTHauth listunipost auth list --json

Compatibility command that reports the single current local or environment credential.

Example response

AUTHauth useunipost auth use ws_1 --json

Compatibility command that sets the default workspace ID for the single local binding.

Example response

CONFIGconfig pathunipost config path --json

Prints the local UniPost CLI config path.

Example response

CONFIGconfig showunipost config show --json

Prints redacted local CLI config, including base URL, defaults, telemetry, and credential locator metadata.

Example response

CONFIGconfig setunipost config set base_url https://dev-api.unipost.dev --json

Sets safe local config keys such as `base_url`, `default_profile_id`, or `default_workspace_id`.

Example response

Profiles & Connect

Manage workspace profiles and create hosted OAuth sessions for social accounts.

PROFILESprofiles listunipost profiles list --json

Lists workspace profiles available to the CLI.

Example response

PROFILESprofiles getunipost profiles get pr_1 --json

Fetches one profile by ID.

Example response

PROFILESprofiles createunipost profiles create --name "Studio" --json

Creates a workspace profile that can own connected accounts and publishing defaults.

Example response

PROFILESprofiles useunipost profiles use pr_1 --json

Stores a profile ID as the default for later CLI commands.

Example response

CONNECTconnect createunipost connect create --platform linkedin --profile pr_1 --json

Creates a hosted OAuth connect session for a platform and profile.

Example response

CONNECTconnect getunipost connect get cs_1 --json

Reads the current status of a connect session.

Example response

CONNECTconnect waitunipost connect wait cs_1 --timeout 300 --json

Polls a connect session until it is completed, expired, canceled, or timed out.

Example response

Accounts

Inspect connected social accounts, platform health, posting capabilities, and account metrics.

ACCOUNTSaccounts listunipost accounts list --json

Lists connected social accounts, with optional platform and profile filters.

Example response

ACCOUNTSaccounts getunipost accounts get sa_1 --json

Finds one account from the workspace account list.

Example response

ACCOUNTSaccounts healthunipost accounts health --account sa_1 --json

Reads account health, token status, scope status, and setup warnings.

Example response

ACCOUNTSaccounts capabilitiesunipost accounts capabilities --account sa_1 --json

Reads the posting and analytics capabilities available for an account.

Example response

ACCOUNTSaccounts metricsunipost accounts metrics --account sa_1 --json

Reads account-level follower and engagement metrics when the platform supports them.

Example response

Posts

Validate, draft, publish, schedule, observe, cancel, and retry UniPost posts.

POSTSposts listunipost posts list --status failed --limit 10 --json

Lists posts, optionally filtered by status and paginated with limit/cursor.

Example response

POSTSposts getunipost posts get post_1 --json

Fetches one post and its per-platform result state.

Example response

POSTSposts analyticsunipost posts analytics post_1 --json

Reads analytics attached to one post.

Example response

POSTSposts validateunipost posts validate --account sa_1 --caption "Shipping with UniPost CLI." --json

Validates a post payload without creating a draft or publishing.

Example response

POSTSposts draftunipost posts draft --account sa_1 --caption "Shipping with UniPost CLI." --json

Creates a UniPost draft without publishing externally.

Example response

POSTSposts createunipost posts create --from-file post.json --dry-run --json

Creates a post. Use `--dry-run` for validation-only; live writes require `--yes` and an idempotency key.

Example response

POSTSposts schedule

unipost posts schedule --account sa_1 --caption "Shipping with UniPost CLI." --at 2026-06-10T09:00:00Z --yes --idempotency-key user-approved-2026-06-10-001 --json

Creates a scheduled post after explicit approval and a stable idempotency key.

Example response

POSTSposts publish-draftunipost posts publish-draft post_1 --yes --idempotency-key user-approved-post-1 --json

Queues an existing draft for publishing after explicit approval.

Example response

POSTSposts waitunipost posts wait post_1 --timeout 120 --json

Polls a post until it reaches a terminal status.

Example response

POSTSposts cancelunipost posts cancel post_1 --yes --json

Cancels a scheduled or queued post after explicit approval.

Example response

POSTSposts retryunipost posts retry post_1 --result res_1 --yes --json

Retries a failed delivery result after explicit approval of the post and result IDs.

Example response

Media

Reserve media uploads, upload local bytes, and wait until media is publish-ready.

MEDIAmedia uploadunipost media upload ./video.mp4 --json

Reserves a media record, uploads the local file, and waits for readiness.

Example response

MEDIAmedia getunipost media get med_1 --json

Fetches one media item by ID.

Example response

MEDIAmedia waitunipost media wait med_1 --timeout 120 --json

Polls a media item until it is ready or failed.

Example response

Analytics

Read workspace, post, and platform analytics summaries.

ANALYTICSanalytics summaryunipost analytics summary --from 2026-06-01 --to 2026-06-30 --json

Loads aggregate analytics for a date range.

Example response

ANALYTICSanalytics postsunipost analytics posts --from 2026-06-01 --limit 10 --json

Lists per-post analytics for a date range.

Example response

ANALYTICSanalytics platformsunipost analytics platforms --json

Lists analytics totals grouped by platform.

Example response

ANALYTICSanalytics platformunipost analytics platform linkedin --from 2026-06-01 --json

Reads analytics for one platform and optional date range.

Example response

Examples

Generate dependency-free examples for direct HTTP calls and hosted MCP setup.

EXexamples posts.createunipost examples posts.create --lang node --account sa_1 --caption "Hello" --json

Generates a cURL or native Node fetch example for creating a post.

Example response

EXexamples mcp.claude-codeunipost examples mcp.claude-code --json

Prints the Claude Code MCP setup command and auth test command.

Example response

Agent & MCP

Give local agents a stable UniPost contract for setup, planning, diagnostics, MCP config, and constrained execution.

AGENTagent bootstrapunipost agent bootstrap --client codex --json

Checks agent readiness and returns next actions for auth, profiles, accounts, and safe draft workflows.

Example response

AGENTagent capabilitiesunipost agent capabilities --json

Returns the stable agent catalog: commands, intents, schemas, status enums, and safety levels.

Example response

AGENTagent contextunipost agent context --json

Returns real workspace, profile, account, recent_posts, recent_post_summary, and default context for agent grounding.

Example response

AGENTagent guideunipost agent guide --client codex --json

Returns client-specific prompt guidance for safe CLI and MCP operation.

Example response

AGENTagent planunipost agent plan --intent create_draft_post --account sa_1 --caption "Hello" --json

Creates a structured, non-executing plan for a supported intent.

Example response

AGENTagent plan-publishunipost agent plan-publish --from-file post.json --json

Alias for planning a live or scheduled publish flow without executing the write.

Example response

AGENTagent executeunipost agent execute --plan safe-plan.json --json

Executes only current structured read-only, validation, or draft-write actions from an agent plan envelope.

Example response

AGENTagent mcp-configunipost agent mcp-config --client codex --json

Generates MCP client configuration for Claude Code, Codex, Cursor, Windsurf, or generic JSON clients.

Example response

AGENTagent mcp-testunipost agent mcp-test --json

Verifies CLI auth and returns the hosted MCP endpoint contract.

Example response

AGENTagent installunipost agent install --client codex --json

Returns first-party instruction package paths and setup guidance for a local agent.

Example response

Self-management & Shell

Inspect, update, and integrate the local CLI binary with shell completion.

SELF--versionunipost --version

Prints the installed CLI version.

Example response

SELF--helpunipost --help

Prints top-level usage, supported commands, global flags, install, and upgrade notes.

Example response

SELFcompletionunipost completion zsh

Prints shell completion for bash, zsh, or fish.

Example response

SELFupgradeunipost upgrade --json

Updates the globally installed CLI package with npm.

Example response

SELFself updateunipost self update --json

Alias for updating the CLI package.

Example response

SELFself helpunipost self help

Prints install, update, version, help, and doctor commands.

Example response