# plotwork publish

> Page: https://docs.plotwork.dev/cli/commands/publish. Index of every page: https://docs.plotwork.dev/llms.txt

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 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](https://docs.plotwork.dev/cli/configuration.md). |
| How do I read this in a terminal? | `plotwork publish --help` |

## Synopsis

```sh
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.

```sh
plotwork publish checkout.diagram
```

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

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

Publish at a public link, behind a stable link.

```sh
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. |

## See also

| Doc | Why |
|---|---|
| [Command reference](https://docs.plotwork.dev/cli/commands.md) | Every command of the command line |
| [Where members publish](https://docs.plotwork.dev/organisations.md#13-where-members-publish) | Where a publish goes, and when it is private |
| [Hosted diagrams](https://docs.plotwork.dev/hosted-diagrams.md) | Public links, stable links and folders |
| [Exit codes and output formats](https://docs.plotwork.dev/cli/exit-codes-and-output.md) | What every code and format means |