@writavo/cli

@writavo/cli

The official command line client for the Writavo Content API.

Draft, edit, organise, schedule and publish a Writavo Site's content from a shell or a script. Every command, flag and type is generated from the published OpenAPI 3.1 specification, so the CLI cannot offer a command the API does not have.

npx @writavo/cli ping

Install

npm install -g @writavo/cli   # then: writavo ping
npx @writavo/cli ping         # or run it without installing

Node 20 or newer.

Authenticate

Create a key in the dashboard under Settings, then API keys. Keys are not created through the API, because creating the first one needs a signed-in person rather than a credential you do not have yet.

export WRITAVO_API_KEY=wv_sk_...
writavo ping

--key overrides the environment variable for one invocation. The key is sent as Authorization: Bearer to https://api.writavo.com/v1 and nowhere else: WRITAVO_API_BASE_URL is honoured only for a loopback address, so nothing that can write a shell profile can redirect your key to another host.

Commands

Every command is named after its operationId in the specification, so a command name is unambiguous and an agent that has read the spec already knows all fifty of them.

writavo                        # groups and global flags
writavo articles               # the commands in one group
writavo create-article --help  # what it does and every flag it takes
writavo commands               # tab-separated, for completion scripts and agents

# Read
writavo list-articles --status published --limit 10 --json
writavo get-article 0f2a8c31-0000-4000-8000-00000000abcd

# Write. Nothing becomes public by accident: publishing is always a separate call.
writavo create-article --title "How autonomous SEO content works" --content "# Draft"
writavo publish-article <id>

# Look before you leap
writavo create-pipeline-run --dry-run

Global flags

Flag	What it does
--key <key>	API key for this invocation. Defaults to $WRITAVO_API_KEY.
--json	Print only the response data, formatted.
--raw	Print the response body exactly as it arrived.
--if-match <version>	Optimistic concurrency, where the command supports it.
--dry-run	Print the request that would be sent, and send nothing.
--quiet, -q	Suppress the rate-limit footer on stderr.

Output and exit codes

The response body goes to stdout; the rate-limit footer, warnings and errors go to stderr, so writavo list-articles > out.json produces clean JSON.

Code	Meaning
0	Success.
1	The API returned an error, or the request could not be sent.
2	Usage error: unknown command, missing flag, bad value, no key.

On an API error the CLI prints the code, the message, the per-field messages where there are any, what to do about it, and the request id to quote to support. The remedy text comes from the same source as the errors page and the MCP server, so the three can never disagree.

Safety

• Idempotency-Key is generated per invocation. It is never asked of you, because a key reused with a different body is a 409 rather than the retry safety it exists to provide.
• Commands that spend credits, make content public, or delete permanently say so in --help.
• --dry-run redacts the key while still showing that one would be sent.

See also

• Documentation · Errors · Rate limits
• @writavo/mcp-server, the same API as MCP tools for an AI assistant
• https://writavo.com/llms.txt, guidance for agents

Licence

MIT. See LICENSE.