# CLI commands and MCP tools

Every command in the Workover CLI (`@workover/cli` 0.11.0), every tool in the Workover MCP server (`@workover/mcp` 0.7.1), and the permission, or scope, each one needs. To install both and sign in, see [Set up your agent](/docs/cli-and-mcp/).

The CLI and the MCP server share one sign-in. `workover login` stores a token in `~/.workover/config.json`, and the MCP server reads the same file, so both have exactly the scopes you approved when you signed in.

## Scopes

A token always holds `read` and `propose`. You add the others by passing a flag to `workover login`, and the browser lists every scope before you approve.

| Scope | Login flag | What the approval screen says | What it unlocks |
| --- | --- | --- | --- |
| `read` | Always granted | Read your documents | Every command and tool marked **Default** below: listing, searching and reading documents, tabs, comments, activity and the style guide |
| `propose` | Always granted | Suggest changes for you to review and accept | Also **Default**: proposing edits as suggestions, creating documents, uploading images, and adding or resolving comments |
| `publish` | `--publish` | Publish to your connected WordPress sites, without asking again | The WordPress and Mintlify publishing routes of the HTTP API. No CLI command or MCP tool publishes. |
| `draft` | `--draft` | Write drafts with AI. This spends AI credits, and signs in to the app you connected in Settings to capture screenshots | `draft`, `draft-set`, `eval`, `doc reshoot`, `doc verify` |
| `write` | `--write` | Edit your documents directly, with no suggestions for you to review | `doc write`, `doc tab-new`, the `--write` option of `doc reshoot` and `doc verify`, `workover_edit_doc`, `workover_create_tab` |
| `rules` | `--rules` | Add and change your style guide rules, which steer all future AI writing for everyone in the workspace | `rules add`, `workover_add_style_rule` |

> **Warning:** `draft` spends AI credits and lets Workover sign in to your connected app with the credential stored in Workover. `write` replaces document text with no review step, so anything left out of the new text is deleted. `rules` changes the style guide for everyone in the workspace. Grant these only on a machine and agent you trust.

No scope reaches your account security, billing or token management. A token with `publish` still cannot push past a “WordPress is newer” conflict: a person has to resolve it in the browser.

## CLI commands

In the tables below, **Default** means the command works with the `read` and `propose` scopes every token holds.

Every document command takes the numeric document id that `workover doc list` and `workover doc search` print as `#123`. Commands that take a body read it from `--file <path>`, or from standard input when you pipe text in. Add `--json` to most commands for machine-readable output.

### Account

![The Developer settings screen showing the Connect a device section and Connected devices list, where CLI tokens appear](https://workover.io/api/proxy-image?url=https%3A%2F%2Fwp.wpdocsync.com%2Fwp-content%2Fuploads%2F2026%2F09%2Fthe-developer-settings-screen-showing-the-connect-a-device-s-scaled.png)

| Command | What it does | Scope |
| --- | --- | --- |
| `workover login [--publish] [--draft] [--write] [--rules] [--client "<name>"]` | Signs in through your browser. `--client` sets the name the token shows under **Connected devices**; the default is “Workover CLI”. Signing in again replaces the token stored on this machine; the old token stays valid, and listed under **Connected devices**, until you revoke it. | None |
| `workover logout` | Revokes this machine’s token and deletes the local file | None |
| `workover whoami` | Shows the server you are signed in to and the start of your token | None |
| `workover projects` | Lists the projects you can reach, with their ids | Default |

### Documents: `workover doc`

| Command | What it does | Scope |
| --- | --- | --- |
| `doc list --project <id>` | Lists the documents in a project | Default |
| `doc search "<query>" [--limit N]` | Finds documents by title and content. Default limit 10. | Default |
| `doc read <docId> [--tab <tabId>] [--html]` | Prints the document’s current text as Markdown, or HTML with `--html` | Default |
| `doc tabs <docId>` | Lists the document’s tabs | Default |
| `doc activity <docId> [--limit N]` | Shows who changed the document and how, newest first. Default limit 20. | Default |
| `doc create --project <id> --title "<title>"` | Creates a document with the body written straight in. There is nothing to accept. | Default |
| `doc propose <docId> [--note "<why>"] [--tab <tabId>]` | Suggests a complete revised version. The changes appear as tracked-change suggestions for a person to accept or reject. | Default |
| `doc write <docId> [--note "<why>"] [--tab <tabId>]` | Replaces the body with no review step | `write` |
| `doc tab-new <docId> --title "<title>" [--parent <tabId>]` | Adds an empty tab | `write` |
| `doc reshoot <docId> [--replace] [--write]` | Workover AI retakes the document’s screenshots from its text. `--replace` drops the old screenshots. The result arrives as suggestions, or is written directly with `--write`. | `draft`, plus `write` for `--write` |
| `doc verify <docId> [--write]` | Workover AI checks the text against the project’s linked repository and corrects what it finds wrong. The result arrives as suggestions, or is written directly with `--write`. | `draft`, plus `write` for `--write` |

> **Warning:** `doc write` replaces the whole body of the document, or of one tab. Anything you leave out is deleted. Run `doc read` first and pass the complete document.

A document with tabs holds several separate bodies. `read`, `propose` and `write` act on one tab: without `--tab` they act on the main body only. Run `doc tabs` first.

### Comments: `workover comments`

| Command | What it does | Scope |
| --- | --- | --- |
| `comments list <docId> [--all]` | Lists open comment threads. `--all` includes resolved ones. | Default |
| `comments add <docId> "<text>" [--to <commentId>] [--quote "<text>"]` | Adds a comment, a reply in a thread with `--to`, or a comment on a passage with `--quote` | Default |
| `comments resolve <commentId>` | Marks a thread resolved | Default |
| `comments reopen <commentId>` | Reopens a resolved thread | Default |

### Style guide: `workover rules`

Each command takes `--project <id>` or `--org <id>`. With a project id, you get the project’s rules and the workspace’s rules together.

| Command | What it does | Scope |
| --- | --- | --- |
| `rules list` | Lists the rules in force | Default |
| `rules export` | Prints the rules as a block to paste into `AGENTS.md` or `CLAUDE.md`, for example `workover rules export --project 11 >> AGENTS.md` | Default |
| `rules add "<the rule>"` | Adds a rule for the project or the whole workspace | `rules` |

### AI drafting and scoring

| Command | What it does | Scope |
| --- | --- | --- |
| `draft --org <id> --project <id> "<brief>" [--ground yes|no|auto] [--type tutorial|how-to|reference|explanation]` | Queues a draft and waits for it, printing Workover’s progress. `--ground` controls whether the draft reads the project’s linked repository; the default is `auto`. Stops waiting after 20 minutes. | `draft` |
| `draft-set --org <id> --project <id> --feature "<name>" [--kind documentation|content] [--dry-run] [--yes]` | Plans a set of articles for a feature, prints the plan, then asks once before drafting. You can answer with the numbers of articles to skip. `--dry-run` prints the plan only. `--yes` skips the question. `--kind` defaults to `documentation`. | `draft` |
| `eval --org <id> --project <id> [--limit N]` | Scores the project’s documents against an editorial rubric, one AI call per document, and prints the weakest criteria and the top fix for each | `draft` |

## MCP tools

| Tool | What it does | Scope |
| --- | --- | --- |
| `workover_search_docs` | Finds documents by title and content | Default |
| `workover_read_doc` | Reads a document, or one tab, with the style guide attached | Default |
| `workover_list_projects` | Lists your projects | Default |
| `workover_list_tabs` | Lists a document’s tabs | Default |
| `workover_style_guide` | Reads a project’s style guide, including workspace-wide rules | Default |
| `workover_create_doc` | Creates a document with its body written straight in, optionally filed under the category names you give it | Default |
| `workover_propose_edit` | Proposes a complete revised document as suggestions | Default |
| `workover_upload_image` | Uploads a local image into a document’s media and returns its URL | Default |
| `workover_edit_doc` | Replaces a document’s body, or one tab, with no review step | `write` |
| `workover_create_tab` | Adds an empty tab | `write` |
| `workover_add_style_rule` | Adds a style guide rule for a project or the whole workspace | `rules` |

Without the scope a tool needs, it returns a permission error. Neither the MCP server nor the CLI publishes to WordPress.

### MCP usage data

The MCP server sends Workover one event per tool call: the tool name, how long it took, whether it succeeded or what kind of failure it was, which MCP client called it, and the MCP server’s version. It never sends your documents, the arguments you pass or the results. To turn it off, set either environment variable:

```
export DO_NOT_TRACK=1
export WORKOVER_TELEMETRY=0
```

## Tokens

| Fact | Detail |
| --- | --- |
| Where you see them | Account settings → **Developer** → **Connected devices**. Each row shows the token’s name, when it was added, and when it was last used or “not used yet”. |
| How you get one | Only by signing in with `workover login`. There is no button to create one. |
| Where it is stored | On your machine in `~/.workover/config.json`, readable only by you. Workover keeps only a hash. |
| Format | Starts with `wk_` |
| Expiry | Tokens do not expire. Revoke them when you no longer need them. |
| Changing scopes | Scopes are fixed when the token is created. Sign in again with different flags to get a new token. |
| Revoking | Click **Revoke** on the token’s row, or run `workover logout` on that machine. Revocation takes effect immediately. |

You can also call the HTTP API directly with a token in an `Authorization: Bearer wk_…` header. The [API reference](/api-reference) lists each endpoint and the scope it needs.

## Related

- [Set up your agent](/docs/cli-and-mcp/)
- [Access tokens](/docs/api-keys/)
- [Style guides](/docs/style-guides/)
- [Comments and suggestions](/docs/comments-and-suggestions/)
- [Document tabs](/docs/document-tabs/)