Command reference

plotwork board add-tab

Add a tab: an empty diagram of a kind, or the source of a file. It is a command of the Plotwork command line, the npm package @buun_group/plotwork.

TL;DR

Question	Answer
What does it do?	Add a tab: an empty diagram of a kind, or the source of a file.
How do I run it?	`npx -y @buun_group/plotwork@0.2.0 board add-tab`, or `plotwork board add-tab` 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 add-tab --help`

Synopsis

plotwork board add-tab <board> --name <name> [--kind <kind>] [--file <file>] [--after <tab>] [--json]

What it does

Adds a tab after --after, or last. With --file the tab starts from that source; otherwise from an empty diagram of --kind.

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
`--name <name>`	Required	The name of the new tab.
`--kind <kind>`	`flow`	The kind of the empty diagram, such as `sequence` or `schema`.
`--file <file>`	Off	Start the tab from this `.diagram` file.
`--after <tab>`	last	Put it after this tab; `first` puts it first.
`--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

Add an empty sequence diagram.

plotwork board add-tab Checkout --kind sequence --name "Checkout calls"

Add a tab from a file.

plotwork board add-tab Checkout --name Schema --file db/schema.diagram

Exit codes

Code	When
`0`	The tab was added.
`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 `--name` is missing.

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