Command reference

plotwork board edit

Change a tab with typed edit operations, which the board rebases on the current source. It is a command of the Plotwork command line, the npm package @buun_group/plotwork.

TL;DR

Question	Answer
What does it do?	Change a tab with typed edit operations, which the board rebases on the current source.
How do I run it?	`npx -y @buun_group/plotwork@0.2.0 board edit`, or `plotwork board edit` once the package is installed.
What does it write?	Nothing on this machine.
Does it use the network?	Yes: calls to the Plotwork API with the key in `PLOTWORK_API_KEY`, which is never printed.
Does it read the repository settings?	No.
How do I read this in a terminal?	`plotwork board edit --help`

Synopsis

plotwork board edit <board> <tab> [--op <json>] [--rename <old=new>] [--set <target.option=value>] [--add-node <id[:type][=label]>] [--add-edge <from->to[=label]>] [--remove <target>] [--remove-edge <from->to>] [--base-version <n>] [--revision <id>] [--json]

What it does

Sends edit operations, applied in the order the flags are typed: --op takes any operation as edit_diagram takes it (rename, set, add_node, remove, add_edge, remove_edge, move, replace_text), and the other flags write the common ones. Each flag may be repeated.

Operations name their targets by id or label, so the board applies them to the current source even when someone changed the tab since; if any does not apply, none is kept and each result says why.

A board is named by its id, its address in the portal (an address with #tab-<id> also names the tab), or its name; a tab by its id or its name. A name costs one more call to look it up.

Options

Option	Default	What it does
`--op <json>`	Off	One operation as JSON, such as `{"op":"move","target":"cache","into":"backend"}`.
`--rename <old=new>`	Off	Rename an id, everywhere it is used.
`--set <target.option=value>`	Off	Set an option, such as `api.tone=accent` or `header.theme=dark`; an empty value removes it.
`--add-node <id[:type][=label]>`	Off	Add a node, such as `cache:database=Redis`.
`--add-edge <from->to[=label]>`	Off	Add an edge, such as `'api->cache=reads'`, quoted so the shell does not read `>`.
`--remove <target>`	Off	Remove a statement by its id or label, with the edges that use it.
`--remove-edge <from->to>`	Off	Remove an edge, such as `'api->db'`, quoted.
`--base-version <n>`	the version read first	The version the operations were written against.
`--revision <id>`	main	A revision of the tab to work on instead of main.
`--json`	Off	Print one JSON document: the API's answer when it worked, or `{ "error": true, "errorCode", "message", "hint", "status" }` when it did not.

Examples

Rename a node and add a cache, in one version.

plotwork board edit Checkout Payments --rename api=gateway --add-node cache:database=Redis

Any operation as JSON.

plotwork board edit Checkout Payments --op '{"op":"move","target":"cache","into":"backend"}'

Exit codes

Code	When
`0`	The board kept the change.
`1`	The API refused the call (its code, words and a hint are printed), or could not be reached.
`2`	A mistake in the command line: an unknown option, a missing operand, a file or glob that matches nothing, or a settings file that cannot be read. Also when `PLOTWORK_API_KEY` is missing or refused, or a flag cannot be read as an operation.

Doc	Why
Command reference	Every command of the command line
Live whiteboards	Boards, tabs, revisions and who may change them
From the command line	Signing in, pull and push, conflicts, and watch
Claude Code plugin	The board and board-sync skills
Exit codes and output formats	What every code and format means