CLI - Overview
Use UniPost from a terminal, or give a local AI agent a safe UniPost toolchain. Pick the setup path that matches what you are trying to do.
What UniPost CLI lets agents do
The CLI gives Codex, Claude Code, and terminal users a safe way to use your real UniPost workspace. It can speed up integration work, inspect connected social accounts, and prepare publishing workflows without turning live publishing into an automatic action.
Connect UniPost faster
Codex or Claude Code can read your project, add UniPost API, SDK, webhook, and environment-variable code, then run local tests and CLI validation against the same workspace.
unipost examples posts.create --lang node --jsonInspect real workspace data
Authenticated agents can retrieve profiles, connected accounts, account health, platform capabilities, and metrics before generating code or planning social workflows.
unipost agent bootstrap --client codex --jsonValidate and draft safely
Agents can generate post payloads, validate them, dry-run publish requests, and create drafts. Live or scheduled publishing is never automatic and still needs explicit user approval.
unipost posts validate --account sa_... --jsonStart in three steps
| Step | What to do |
|---|---|
| 1. Install and sign in | Install once with npm install -g @unipost/cli, then run unipost init or the Dashboard setup-token command. After install, use <code>unipost</code> commands everywhere. Update with <code>unipost upgrade</code> when you need the latest CLI. |
| 2. Choose who will use it | Use Terminal for human command-line work. Use Codex or Claude Code when a local agent should read project code, query UniPost context, and help implement or validate workflows. |
| 3. Ground before action | Run auth status, profiles list, accounts list, or agent bootstrap before drafting. Agents should validate, dry-run, or draft first; live publishing requires --yes and --idempotency-key. |
Dashboard setup tokens, npm-installed unipost commands, and existing API-key login are available now. On macOS, setup-token and API-key login store a secure local CLI credential; UNIPOST_API_KEY remains the CI-friendly fallback. Browser/device auth remains a later auth surface; for direct production integrations, use the REST API, SDKs, or MCP.
Before you run a command
| What you run | What it actually does |
|---|---|
npm install -g @unipost/cli | Install once. This creates the persistent unipost command in your shell. |
unipost ... | The normal command prefix after install. Use this in Dashboard setup-token commands, terminal workflows, and agent setup. |
unipost upgrade | Updates the installed CLI package with npm, then you can run unipost --version to confirm. |
unipost self help | Shows CLI install, update, version, and help commands. |
| Dashboard setup-token command | Exchanges the one-time token for a named CLI key when no valid local binding exists. If the current binding is still valid, the CLI returns already_configured and does not consume the token. |
codex, claude, or another agent command | A separate local AI agent. UniPost CLI does not install those programs. |
Choose your setup path
The setup token only logs the UniPost CLI in. It does not install or configure Codex, Claude Code, or any other agent. If you only want to use UniPost from a terminal, follow Path A. If you want a local AI agent to use UniPost, finish Path A first, then follow Path B.
Path A: Command line only
| Step | What to do |
|---|---|
| 1. Install once | Run npm install -g @unipost/cli, then confirm unipost --help works. |
| 2. Choose a credential path | Run unipost init --api-key up_live_... --json when you already have a key, or open Dashboard -> Project -> API Keys -> Set up UniPost CLI and copy the generated setup-token command. |
| 3. Run it exactly | Run the copied Dashboard command as-is, or run unipost init --api-key <key> --json. Dashboard commands should include --setup-token, --client terminal, --base-url, and --json. To replace an existing local binding, run unipost auth logout --json first or rerun with --replace-key after confirming the new workspace. |
| 4. Verify auth | Run unipost auth status --json. Confirm the credential source and base_url match the environment you are using. |
| 5. Discover real IDs | Run unipost profiles list --json, unipost accounts list --json, and unipost accounts health --account sa_... --json before validating or drafting posts. |
Path B: Local AI agent
Path B is for Codex, Claude Code, Cursor, or another local agent that should operate UniPost safely. This path does not install the agent executable itself; install or open that agent separately if its own command is missing.
| Step | What to do |
|---|---|
| 1. Finish CLI auth | Complete Path A first. The agent will reuse the same UniPost CLI credentials and config. |
| 2. Add UniPost instructions | Run unipost agent install --client codex --json or unipost agent install --client claude-code --json, then follow the returned instruction package setup. |
| 3. Start the agent with grounding | In the agent session, have it run unipost agent bootstrap --client codex --json, agent capabilities, and agent context before it plans or writes anything. Agent context includes workspace, profiles, accounts, recent posts, and a recent post summary. |
| 4. Keep publish safe | Agents should validate, draft, or dry-run first. Live or scheduled publish still requires explicit user approval plus --yes and --idempotency-key. |
Configure the CLI
The CLI stores non-secret settings such as base_url and default_profile_id in its local config file. Production defaults to https://api.unipost.dev. When validating the development environment, set base_url to https://dev-api.unipost.dev.
Common issues
| Problem | Fix |
|---|---|
zsh: command not found: unipost | Install the CLI once with npm install -g @unipost/cli, then open a new terminal and run unipost --help. If it still fails, check that your npm global bin directory is on PATH with npm bin -g. |
| Need the latest CLI | Update with unipost upgrade, then run unipost --version to confirm the installed version. |
| Codex or Claude Code still does not know UniPost after setup-token login | The setup token signs in the UniPost CLI only. Run unipost agent install --client codex --json or unipost agent install --client claude-code --json, then follow the returned instruction package setup in that agent. |
codex or claude command is missing | Install or open that AI agent separately. UniPost CLI does not install Codex, Claude Code, or any other local agent executable. |
| API key is missing or invalid | Use the Dashboard setup token flow first. If you are running in CI, set UNIPOST_API_KEY, then run unipost auth status --json. |
| Replacing the local account binding is blocked | UniPost CLI keeps one local binding. Run unipost auth logout --json first, or rerun the login/init command with --yes after confirming the new workspace should replace the old one. |
setup_token_invalid, setup_token_expired, or setup_token_used | Create a fresh Dashboard setup token. Setup tokens are short-lived and single-use, so copy the newest command from Dashboard before retrying. |
keychain_unavailable | The CLI could not store the named key in secure local storage. On Linux, Windows, or CI, use UNIPOST_API_KEY, pass --api-key for one-off commands, or rerun with --metadata-only if you only want redacted metadata. |
| Wrong API URL | Copy the newest Dashboard setup command; it includes --base-url for the current environment. If you are configuring manually, run unipost config set base_url https://dev-api.unipost.dev --json for dev validation. |
| No profile or account IDs | Run unipost profiles list --json, unipost quickstart --name "Brand" --json, or unipost connect create --json, then check unipost accounts list --json. |
| Live publish is blocked | Start with posts validate, posts draft, or posts create --dry-run. Only add --yes and --idempotency-key after the user explicitly approves live or scheduled publishing. |
Command groups
This overview keeps the setup path and safety model short. For every supported command, copyable examples, and sample JSON responses, open the CLI Reference. For plain-language prompts that tell Codex or Claude Code how to use the CLI, open the AI Agent Guide.
| Group | Commands |
|---|---|
| CLI self-management | upgrade, self update, self help, --version, --help, and completion. |
| Auth and config | init, auth login --api-key, Dashboard setup-token login, auth logout, auth status, config path, config show, config set base_url, and config set default_profile_id. auth list and auth use remain compatibility commands for the single current binding. |
| Quickstart | init, doctor, quickstart, profiles list/create/get/use, and connect create/get/wait. |
| Accounts | accounts list, accounts get, accounts health, accounts capabilities, and accounts metrics. |
| Posts | posts list, posts get, posts analytics, posts validate, posts draft, posts create --dry-run, posts create, posts schedule, posts publish-draft, posts wait, posts cancel, and posts retry. |
| Media | media upload, media get, and media wait. |
| Analytics | analytics summary, analytics posts, analytics platforms, and analytics platform. |
| Examples | examples posts.create plus examples mcp.claude-code for hosted MCP setup. |
| Agent | agent bootstrap, agent capabilities, agent guide, agent context, agent mcp-config, agent mcp-test, agent install, agent plan, agent plan-publish, and restricted agent execute. |
Safe publishing model
Phase 5 keeps publish-capable commands behind the same guardrails. Validation, draft creation, media upload, readiness waits, dry-runs, MCP auth tests, and instruction setup stay safe without --yes; live and scheduled publishing require explicit approval plus a stable idempotency key. The agent execute beta only runs current agent plan --json envelopes with matching catalog_version and structured read-only, validate, or draft-write actions; it rejects stale plans, live publish actions, pending confirmations, and raw command strings.
| Action | Non-interactive rule |
|---|---|
| Validate | Allowed without --yes. |
| Draft | Allowed without --yes; it does not publish externally. |
| Dry-run | Allowed without --yes because it validates and previews only. |
| Live publish | Requires --yes and --idempotency-key. |
| Scheduled publish | Requires --yes and --idempotency-key because it eventually posts externally. |
| Cancel or retry | Requires explicit resource IDs and --yes. |
Agent contract
Codex, Claude Code, Cursor, and other agents should use agent bootstrap, agent capabilities, agent context, agent mcp-config, agent mcp-test, agent install, and agent plan before writing. The contract keeps account discovery, planning, validation, draft creation, and live-publish approvals explicit.
| Primitive | Contract |
|---|---|
| Capability catalog | Returns supported intent names, input schemas, safety levels, canonical actions, and catalog_version. |
| Context grounding | Returns real workspace, profile, account, defaults, and setup-readiness context. |
| Agent guide | Returns client-specific prompt guidance for safe validate/dry-run-before-publish workflows. |
| Agent plan | Returns structured actions for draft or publish intent, including missing inputs and required user confirmations. |
| MCP bridge | examples mcp.claude-code, agent mcp-config, and agent mcp-test bootstrap the hosted MCP endpoint without replacing MCP. |
| Instruction packages | agent install --client codex|claude-code points agents at first-party instructions for safe UniPost operation. |
| Execute beta | agent execute --plan plan.json accepts only current agent plan --json envelopes, uses the registry safety level instead of plan-provided safety_level, and rejects live publish plans. |
| Async waits | connect wait, posts wait, and media wait let agents observe terminal state instead of polling blindly. |
| Status enums | CLI JSON normalizes backend aliases such as cancelled to canonical canceled. |
JSON and exit codes
Every agent-relevant Phase 5 command supports a stable envelope. Machine fields such as code, normalized_code, catalog_version, and status stay stable English identifiers even when human messages are localized.
| Exit code | Meaning |
|---|---|
| 0 | success |
| 1 | generic error |
| 2 | invalid arguments |
| 3 | missing required input |
| 4 | authentication failure |
| 5 | authorization failure |
| 6 | validation failure |
| 7 | upstream UniPost API failure |
| 8 | network failure |
| 9 | unsafe action blocked |
| 10 | timeout |