Command reference

plotwork board import

Import a file, a hosted link, or a library diagram as a new tab, and print what the converter left out. It is a command of the Plotwork command line, the npm package @buun_group/plotwork.

TL;DR

Question	Answer
What does it do?	Import a file, a hosted link, or a library diagram as a new tab, and print what the converter left out.
How do I run it?	`npx -y @buun_group/plotwork@0.2.0 board import`, or `plotwork board import` 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 import --help`

Synopsis

plotwork board import <board> <file|url> [--format <format>] [--name <name>] [--after <tab>] [--json]

What it does

Reads the file on this machine and sends its text: a .diagram file as source, an .svg as a Plotwork picture with its source, a .mmd file as Mermaid, and any other file as one of import-source's formats, named by --format. An https address is a hosted Plotwork picture, and library:<id>, personal:<id> and pattern:<id> name a library diagram, one of the member's own, or a pattern. The API converts it in memory and keeps only the diagram it made.

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
`--format <format>`	from the extension	What the file is: `diagram`, `svg`, `mermaid`, or one of `import-source`'s formats, such as `sql`, `openapi`, `terraform` or `compose`.
`--name <name>`	from the diagram	The name of the new tab.
`--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

Draw a SQL schema as a new tab.

plotwork board import Checkout db/schema.sql --format sql

Import a diagram of the organisation's library, linked to it.

plotwork board import Checkout library:4f1c2b9e-1d2a-4c3b-9e8f-0a1b2c3d4e5f

Exit codes

Code	When
`0`	The tab was made; the notes say what was left out.
`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 the file cannot be read or its format named.

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