CoAuthor CLI

@clickminded/coauthor-cli installs the coauthor command for working with CoAuthor projects from a terminal or from AI coding agents such as Codex, Claude Code, Cursor, and other local agents.

The CLI connects to CoAuthor at https://tools.clickminded.com/coauthor. Your projects stay private and every project command requires browser/device login.

Requirements

• Node.js 20 or newer.
• A CoAuthor account with access to CoAuthor.

Install

Install globally:

npm install -g @clickminded/coauthor-cli

Or run without a global install:

npx @clickminded/coauthor-cli help

Sign In

Start browser/device login:

coauthor auth login

The CLI opens a browser approval page. After approval, it stores a scoped local token for your signed-in CoAuthor account.

Check your login:

coauthor auth status --json

Log out and revoke the local token:

coauthor auth logout

Normal logout removes the local credential only after remote revocation succeeds or the server confirms the token was already revoked or expired. If the server cannot confirm revocation, the CLI keeps the credential so you can retry safely.

To deliberately remove only the local credential while leaving the remote token potentially active:

coauthor auth logout --local-only

Use --local-only only when you explicitly accept that the remote token may remain usable until it expires or is revoked elsewhere.

Local credentials are stored at ~/.coauthor/config.json with best-effort 0600 permissions. Do not print, paste, or commit this file.

Agent Skills

Install agent instructions after installing the CLI:

coauthor skills install all

Install one target at a time:

coauthor skills install codex
coauthor skills install claude
coauthor skills install cursor
coauthor skills install agents

Default install paths are:

• Codex: ~/.codex/skills/coauthor/SKILL.md
• Claude: ./.claude/skills/coauthor/SKILL.md
• Cursor: ./.cursor/rules/coauthor-cli.mdc
• Agents: ./.agents/skills/coauthor/SKILL.md

Use --dry-run to preview, --force to overwrite existing files, and --cwd <path> to install project-local Claude, Cursor, or Agents skills into a specific project.

Skill installs are recorded in ~/.config/coauthor/managed-skills.json. Future package updates automatically refresh recorded skill files when they still match the previously installed template. If you edit a skill file by hand, the auto-update leaves it alone until you run coauthor skills install <target> --force.

Common Commands

Create and inspect projects:

coauthor project create --title "Post title" --topic "Post brief" --audience "Target reader" --json
coauthor project create --contract '{"topic":"Post topic","angle":"Specific angle","target_audience":"Target reader","must_include":["Point to cover"]}' --json
coauthor project list --json
coauthor project show <project-id> --json
coauthor workspace show <project-id> --json

Work with the project:

coauthor chat <project-id> --message "Refine the angle for this post" --json
coauthor workflow status <project-id> --json
coauthor workflow run <project-id> --target draft --wait --json
coauthor workflow run <project-id> --target draft --planning-model gpt-5.6-sol --writing-model gpt-5.6-terra --wait --json
coauthor workflow resume <project-id> --target draft --wait --json
coauthor credits <project-id> --json
coauthor share <project-id> --json

List and save text model preferences:

coauthor models list
coauthor models preferences show --json
coauthor models preferences set --planning-model gpt-5.6-sol --writing-model gpt-5.6-terra --json

Both plans can select any supported user-visible model. Starter includes 2,500 credits per monthly subscription-anniversary period and cannot use customer API keys. Pro includes 6,000 credits and uses included credits first, then a compatible configured provider key. A provider key is never required merely to select a model while included credits remain. Drip tags alone determine customer access and plan; subscription observations are diagnostic and set anniversary timing only. All statuses are retained, only active observations can promote an anchor, and renewal observations do not reset credits. The Supabase admins table is the canonical cross-surface admin bypass source.

Read or generate artifacts:

coauthor contract show <project-id> --json
coauthor outline generate <project-id> --planning-model claude-opus-4-8 --json
coauthor research-plan generate <project-id> --planning-model gpt-5.6-sol --json
coauthor research run <project-id> --wait --json
coauthor draft generate <project-id> --writing-model gpt-5.6-terra --wait --json
coauthor draft get <project-id> --format markdown --json

Images and social content:

coauthor image list <project-id> --json
coauthor image generate <project-id> --placeholder-id <placeholder-id> --prompt "Image direction" --json
coauthor thread generate <project-id> --writing-model gpt-5.6-terra --json

Use --json when another tool or agent needs to parse command output. Use --wait when starting longer-running work and you want the command to wait for completion.

Draft Export

Export a finished draft in the format you need:

coauthor draft get <project-id> --format markdown --json
coauthor draft get <project-id> --format html --json
coauthor draft get <project-id> --format text --json
coauthor draft get <project-id> --format json --json

Markdown, HTML, and text exports resolve generated image URLs when images are available. Use --format json or omit --format for the raw editor document JSON.

Live Actions

Publishing and external exports are real side effects. The default login grants project/workflow access only. To run live publish/export commands, sign in with publish permission:

coauthor auth login --with-publish

Then run live actions only when you mean to publish or export:

coauthor publish thread <project-id> --yes --json
coauthor export blog <project-id> --yes --slug "post-slug" --json
coauthor export clickminded <project-id> --yes --json
coauthor export wordpress <project-id> --yes --slug "post-slug" --json
coauthor operation status <operation-key> --json

For multiple WordPress connections, include --connection-id <id>.

Live actions require both publish scope and --yes.

Agent Usage Rules

Agents should:

• Prefer coauthor commands over browser automation, hand-written HTTP requests, or direct database access.
• Use --json for machine-readable output.
• Use --wait when starting asynchronous work and the user expects the result.
• Treat status: "credits_exhausted" or paused_credits_exhausted as a recoverable Starter pause. Report the supplied reset_at, allowance, used, held, and remaining, then resume after credits reset; do not tell a Starter user to add an API key.
• Treat status: "requires_key" or paused_requires_key as a recoverable Pro pause. Report the compatible required provider, ask the user to add that key in CoAuthor AI settings, then resume with coauthor workflow resume <project-id> --wait --json.
• Treat coauthor_access_required as an access failure and entitlement_sync_unavailable as a temporary verification outage. Do not retry blocked credit-spending commands in a loop.
• Treat status: "research_running_stale" as a stale research run and inspect coauthor research structured <project-id> --json before retrying.
• Check operation status after timeouts, interruptions, network errors, or uncertain live-action results.
• Never print tokens, cookies, provider keys, service-role keys, or authorization headers.

Security

• Tokens are scoped CoAuthor API tokens, not browser cookies.
• Default login grants workflow/project scopes only.
• Publish/export scope is granted only when login is started with --with-publish.
• Tokens are stored locally at ~/.coauthor/config.json.
• Run coauthor auth logout to revoke the current token and then remove local credentials. A failed revoke preserves the local credential for retry; --local-only explicitly skips remote revocation.

Troubleshooting

No token configured means the CLI has no saved CoAuthor credential. Run coauthor auth login.

insufficient_scope means the token does not include the required scope. For publish/export, log in again with coauthor auth login --with-publish.

authorization_pending during login is normal while the browser approval page is waiting for approval.

If auth logout cannot confirm remote revocation, it leaves ~/.coauthor/config.json intact and exits with an error. Retry normal logout when connectivity recovers. Use auth logout --local-only only to abandon remote revocation and remove the local credential anyway.

coauthor_access_required means the signed-in account no longer has verified CoAuthor access. A device token does not grant product access by itself. auth status and auth logout remain available, and an unexpired token works again if access is restored.

entitlement_sync_unavailable means Drip verification is temporarily degraded. Read-only inspection may remain available, but new credit-spending work is blocked until synchronization recovers. Login retries verification immediately, and scheduled reconciliation continues retrying with backoff; do not loop write commands while degraded.

credits_exhausted or paused_credits_exhausted means a Starter workflow is safely paused until the response's reset_at. Report its allowance, used, held, and remaining so the pause can be explained without guessing. Starter does not support BYOK.

requires_key or paused_requires_key means Pro included credits are exhausted and no usable compatible provider key is configured. Open CoAuthor AI settings, add one of the response's required_providers, then run coauthor workflow resume <project-id> --wait --json.

byok_not_allowed means the current plan cannot create, validate, or use provider keys. Starter users can delete a retained key from an earlier Pro period, but it remains inactive unless Pro access returns.

research_running_stale means a research run is still marked running beyond the expected progress window. Inspect coauthor research structured <project-id> --json; if it only contains empty section shells, rewind research or report the stale run instead of repeatedly resuming.

Image generation requires an existing image placeholder. Run coauthor image list <project-id> --json after draft generation and pass the placeholder id to coauthor image generate <project-id> --placeholder-id <placeholder-id> --json.