---
title: "The API, from a shell"
description: "Drive the whole API from a shell or a script."
canonical: "https://writavo.com/docs/cli"
last-updated: "2026-09-23"
---

# The API, from a shell

Drive the whole API from a shell or a script.

## Install

Or run it without installing (best for CI and one-off scripts):

Node 20 or newer.

## Authenticate

Sign in through the browser: the CLI prints a link and a short code, you approve it in the dashboard and choose the Site. The key is generated on your machine; only its hash is sent.

No browser, or in CI? Create a key under Settings > API keys and set it in the environment:

- Key order: `--key`, then `WRITAVO_API_KEY`, then the key saved by `login` in `~/.config/writavo/credentials.json`.
- `logout` forgets the saved key on this machine. To end it everywhere, revoke it under Settings > API keys.
- The key is only ever sent as `Authorization: Bearer` to the published base URL. `WRITAVO_API_BASE_URL` works only for a loopback address, so a tampered shell profile cannot redirect your key.
- `--dry-run` prints the request with the key redacted and sends nothing.

## Finding a command

Each command is named after its operation id in the specification, so anything that has read the specification already knows all.

## Using it

The response body goes to standard output and everything else to standard error, so a redirect gives clean JSON:

## Exit codes

- `0` succeeded.
- `1` the API returned an error, or the request could not be sent.
- `2` usage error: unknown command, missing flag, bad value, or no key. Nothing was sent.

A 2 will never succeed on retry; a 1 might.

> On an API error the CLI prints the code, the message, any per field messages, what to do, and the request id to quote to support. The advice matches the [errors page](/docs/errors) and the MCP server.

## What it will not let you do by accident

- `Idempotency-Key` is generated for each invocation, never asked of you (a key reused with a different body is a `409`).
- A missing required flag is refused before anything is sent, so a billable command never costs a wasted request.
- Commands that spend credits, publish to your live site, or delete permanently say so in `--help`, in those words.
- A key is never printed. `--dry-run` shows `Bearer <redacted>` where it would go.

## See also

- [The MCP server](/docs/mcp) exposes the same API as tools for an AI assistant.
- [The OpenAPI specification](https://writavo.com/openapi.json) generates both; use it to generate your own client.
- [llms.txt](https://writavo.com/llms.txt) tells an agent when to use Writavo and how to call it.