Docs

The unspar CLI one install, one login

A single static binary for macOS, Linux and Windows. Create articles from a brief, wait for the draft, read the markdown and publish to an outlet, all from the terminal or a script.

Install

macOS and Linux:

curl -fsSL https://app.unspar.com/install.sh | sh

Windows PowerShell:

irm https://app.unspar.com/install.ps1 | iex

The installer downloads a single static binary for your platform (Intel and ARM) and verifies its checksum before it is put in place. No runtime, no package manager. Check the result with unspar version.

Log in

unspar login

This opens https://app.unspar.com/cli/authorize in your browser and shows a short code to confirm. On that page you pick:

The team the CLI should act for.
Permissions. Full access is the default; narrow it to read-only or a custom set if the machine only needs part of the workflow.
Projects. All projects are pre-selected; untick the ones this login should not reach.
Expiry. 90 days by default. Log in again to renew.

After approval the CLI stores a team API key for that machine. Run unspar whoami to see which team, permissions and projects it resolved to.

Use an existing API key instead

If you prefer a key you created under Team settings, API keys, hand it to the CLI once:

unspar login --api-key

In CI or on a server, set UNSPAR_API_KEY in the environment and the CLI uses it without a stored login. Keep the key in your secret store, never in a repository.

Write and publish an article

unspar projects list
unspar articles create --project prj_xxx --brief "How small bakeries pick a domain name" --wait
unspar articles content art_xxx --format markdown --output article.md
unspar articles publish art_xxx --outlet out_xxx

Pick a project. unspar projects list shows the id, name and language of each project you can reach. unspar projects show prj_xxx adds the default template, voice and outlet.
Create the article. The brief is the whole instruction: what the piece covers, who reads it, what to avoid. Optional flags: --title, --language, --template, --outlet. With --wait the command polls until the run reaches a final status. Without it, unspar articles status art_xxx --wait does the same later.
Read the result. unspar articles content art_xxx prints the finished markdown; --output writes it to a file. unspar articles show art_xxx --json adds the research sources.
Publish on approval. unspar articles publish art_xxx --outlet out_xxx schedules publication to a connected outlet. unspar outlets list shows which destinations are ready.

unspar articles retry art_xxx restarts a failed run and unspar articles cancel art_xxx stops one that is still generating.

Scripting with --json

Every command supports --json, so the CLI drops straight into shell scripts, CI jobs and other agents:

unspar projects list --json
unspar credits balance --json
unspar articles status art_xxx --json

unspar --help lists everything, and each command documents its own fields and flags in unspar <command> --help.

Local MCP server

If you would rather not use the hosted MCP server, the CLI serves the same tools locally over stdio, reusing your CLI login:

claude mcp add unspar -- unspar mcp serve
codex mcp add unspar -- unspar mcp serve

The local server exposes 19 tools. On top of the hosted set it adds unspar_auth_env, unspar_article_approve and unspar_project_create. It resolves credentials at each tool call, so a login or a changed UNSPAR_API_KEY applies after you restart the MCP process.

Agent skill file

A skill file teaches Claude Code, Codex and similar agents the Unspar workflow: which commands to run, how to wait for generation and when to publish. Put it in your project and the agent picks it up automatically:

mkdir -p .claude/skills/unspar && curl -fsSL https://app.unspar.com/skills/unspar/SKILL.md -o .claude/skills/unspar/SKILL.md

Codex reads the same file from .agents/skills/unspar/SKILL.md.

Command reference

Command	What it does
`unspar login`	Browser login. `--api-key` stores an existing team API key instead.
`unspar whoami`	Show the team, permissions and projects the current credential resolves to.
`unspar auth env`	Print the resolved profile and URLs without touching credentials or the network.
`unspar projects list`, `show`	List projects, or show one with its default template, voice and outlet.
`unspar articles create`	Create an article from `--brief` in `--project` and start generation. `--no-queue` stores a draft without spending credits; `unspar articles queue` starts it later.
`unspar articles status`	Read the status once, or poll with `--wait`.
`unspar articles content`, `show`	Print the finished markdown, or the article record with its sources.
`unspar articles publish`	Schedule publication to `--outlet`, now or at `--scheduled-at`.
`unspar articles retry`, `cancel`, `approve`	Restart a failed run, stop a running one, or release one that is waiting for a decision.
`unspar outlets list`, `templates list`, `voices list`	List publishing destinations, templates and voice profiles.
`unspar credits balance`, `transactions`	Remaining credits and recent credit movements.
`unspar mcp serve`	Serve the local MCP server over stdio.
`unspar api get <path>`	Read-only escape hatch for API paths without a native command.

Credits and safety

Creating, queuing and retrying an article spends team credits. Publishing sends content to a destination outside Unspar. These commands ask before acting; pass --yes only in scripts where that intent is already settled.
--dry-run builds the request offline and shows it without credentials or network access.
Every write sends an idempotency key automatically, so a retried command is not applied twice.
A run that failed because a source could not be fetched is not fixed by a retry. Read status_reason first.

Previous Docs overview Next Hosted MCP →