# plotwork board import

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

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

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

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

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

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

## See also

| Doc | Why |
|---|---|
| [Command reference](https://docs.plotwork.dev/cli/commands.md) | Every command of the command line |
| [Live whiteboards](https://docs.plotwork.dev/live-whiteboards.md) | Boards, tabs, revisions and who may change them |
| [From the command line](https://docs.plotwork.dev/live-whiteboards.md#9-from-the-command-line) | Signing in, pull and push, conflicts, and watch |
| [Claude Code plugin](https://docs.plotwork.dev/agents/claude-code-plugin.md) | The board and board-sync skills |
| [Exit codes and output formats](https://docs.plotwork.dev/cli/exit-codes-and-output.md) | What every code and format means |