Command reference

plotwork publish

Save every diagram of a .diagram or Markdown file to Plotwork, where your organisations' Publishing settings decide, and print the link. It is a command of the Plotwork command line, the npm package @buun_group/plotwork.

TL;DR

Question	Answer
What does it do?	Save every diagram of a `.diagram` or Markdown file to Plotwork, where your organisations' Publishing settings decide, and print the link.
How do I run it?	`npx -y @buun_group/plotwork@0.1.0-beta.13 publish`, or `plotwork publish` once the package is installed.
What does it write?	Nothing on this machine.
Does it use the network?	Yes: one request to the Plotwork API for each diagram, with the key in `PLOTWORK_API_KEY`, which is never printed. The source is sent, and the repository's header defaults and brand; nothing else of the file.
Does it read the repository settings?	Yes: the header defaults of the settings file apply to every diagram. See Configuration.
How do I read this in a terminal?	`plotwork publish --help`

Synopsis

plotwork publish <file> [--org <slug>] [--personal] [--folder <path>] [--name <name>] [--alias <name>] [--theme light|dark|auto] [--embed-source] [--config <file>]

What it does

Checks every diagram of the file on this machine, then stores each one through the hosted API with the key in PLOTWORK_API_KEY. Where it goes is the API's decision: an organisation that keeps its members' diagrams in its private library gets it there, and the link printed is its page for members; otherwise it goes to your own library at a public link. A file with a mistake publishes nothing.

A Markdown file publishes each diagram fence, named after the file and numbered. Publishing the same diagram again keeps its link.

Options

Option	Default	What it does
`--org <slug>`	where your organisations' settings send it	Save it to this organisation's private library.
`--personal`	Off	Ask for a public link in your own library; an organisation that requires its library refuses it.
`--folder <path>`	the top level	The folder to file it in, such as `Payments/Checkout`.
`--name <name>`	the file name	The name it is listed under.
`--alias <name>`	Off	Point a stable link with this name at it, so one address shows the latest version. Personal only, and one diagram only.
`--theme light\|dark\|auto`	the settings default, else `light`	The colour scheme to draw it in.
`--embed-source`	Off	Write the source into the stored picture so it can be edited later; `--no-embed-source` leaves it out.
`--config <file>`	`PLOTWORK_CONFIG`, else the nearest `plotwork.config.json` or `.plotwork/config.json` from the file up to the repository root	The repository settings file to read: header defaults, and the style rules check applies.

Examples

Save it where your organisations send it, and print the link.

plotwork publish checkout.diagram

Save every diagram of a Markdown file to Acme's library, in a folder.

plotwork publish docs/architecture.md --org acme --folder Platform

Publish at a public link, behind a stable link.

plotwork publish flow.diagram --personal --alias checkout-flow

Exit codes

Code	When
`0`	Every diagram was saved, and its link printed.
`1`	A diagram has a mistake (nothing is sent), the API refused one (its code and words are printed), or the API 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, `--personal` and `--org` are both given, or `--alias` is given for a file with several diagrams.

Doc	Why
Command reference	Every command of the command line
Where members publish	Where a publish goes, and when it is private
Hosted diagrams	Public links, stable links and folders
Exit codes and output formats	What every code and format means