@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 login

Install

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

Node 20 or newer.

Authenticate

writavo login     # prints a link and a code; approve in the browser
writavo whoami    # which Site and key are in use, checked against the API
writavo logout    # delete the saved sign-in from this machine

writavo login prints a link and a short code. Open the link, sign in (or create an account and finish onboarding first; the code is kept for you), check the code, choose the Site and approve. The command waits and exits once you have; Ctrl-C cancels and saves nothing.

The key is generated on your machine and only its hash is sent for approval, so it never crosses the network until it is used. It is limited to the Site you chose, never carries key or webhook management, and expires after 90 days. It is saved to ~/.config/writavo/credentials.json ($XDG_CONFIG_HOME is honoured; %APPDATA%\writavo on Windows), mode 0600 in a 0700 directory. The MCP server (@writavo/mcp-server) reads and writes the same file, so signing in with one signs in the other. logout deletes the file; the key itself works until you revoke it in the dashboard under Settings, then API keys, or it expires.

A key you created yourself works too, and always takes precedence over the saved sign-in:

export WRITAVO_API_KEY=wv_sk_...
writavo whoami

--key overrides both for one invocation. The order is --key, then WRITAVO_API_KEY, then the saved sign-in. 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, then the saved sign-in.
--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.
130	writavo login was cancelled with Ctrl-C.

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.