plotwork board pull
Write a tab's source to a file, and record the version it pulled beside it. It is a command of the Plotwork command line, the npm package @buun_group/plotwork.
TL;DR
| Question | Answer |
|---|---|
| What does it do? | Write a tab's source to a file, and record the version it pulled beside it. |
| How do I run it? | npx -y @buun_group/plotwork@0.2.0 board pull, or plotwork board pull once the package is installed. |
| What does it write? | The file and its .board.json sidecar, unless --out - is given. |
| 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 pull --help |
Synopsis
plotwork board pull <board> <tab> [--revision <id>] [--out <file>] [--force] [--json]What it does
Writes the tab's source to --out, or to the tab's name as a .diagram file, and the version it pulled to <file>.board.json beside it, which board push sends that version from. The sidecar holds the board, tab and revision ids, the version, and a hash of the file; never a key or the source. It can be committed with the file.
A file that changed since it was pulled, or one that was never pulled from this tab, is not overwritten without --force. Pulled again, it prints what changed on the board since the version the file had.
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. |
--out <file> | the tab's name as a .diagram file | The file to write; - prints the source instead, and records nothing. |
--force | Off | Overwrite a file that changed since it was pulled, or that was not pulled from this tab. |
--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
Pull the Payments tab into the repository.
plotwork board pull Checkout Payments -o docs/payments.diagramPull a revision of the tab.
plotwork board pull Checkout Payments --revision Rv7kP2mQ9xWaExit codes
| Code | When |
|---|---|
0 | The source was written, or printed. |
1 | The API refused the call, could not be reached, or the file has changes of its own and --force was not given. |
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. |
See also
| 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 |