Command reference

plotwork board push

Send a file as the new source of a tab, against the version it was pulled at; a conflict is explained, never overwritten. It is a command of the Plotwork command line, the npm package @buun_group/plotwork.

TL;DR

Question	Answer
What does it do?	Send a file as the new source of a tab, against the version it was pulled at; a conflict is explained, never overwritten.
How do I run it?	`npx -y @buun_group/plotwork@0.2.0 board push`, or `plotwork board push` once the package is installed.
What does it write?	The sidecar, with the new version, after a push the board kept.
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 push --help`

Synopsis

plotwork board push <file> | <board> <tab> <file> [--revision <id>] [--force] [--json]

What it does

Checks the file on this machine, then sends its whole source as the tab's new version, against the version its sidecar recorded. With only <file>, the board, tab and revision come from the sidecar. A file that has not changed since it was pulled sends nothing.

When someone changed the tab since that version, the board refuses the push with diagram.version_conflict. The command then prints who changed what since, how the file differs from the tab now, and what to do: pull and redo the change, send it as edits with board edit (which the board rebases), or --force, which replaces the board's version with the file. The tab's history keeps the version it replaced.

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
`--revision <id>`	main	A revision of the tab to work on instead of main.
`--force`	Off	Send against the tab's current version, replacing whatever changed since the file was pulled, or a file that was never pulled.
`--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

Send a pulled file back to its tab.

plotwork board push docs/payments.diagram

Replace the tab's source with a file that was never pulled.

plotwork board push Checkout Payments docs/payments.diagram --force

Exit codes

Code	When
`0`	The tab has the file's source, or the file had not changed.
`1`	The file has errors (nothing is sent), the tab changed since the file was pulled (a conflict, explained), or the API refused it.
`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 the file has no sidecar for the tab and `--force` was not given.

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