# plotwork board push

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

Send a file as the new source of a tab, against the version it was pulled at; a conflict is explained, never overwritten. It is a command of the Plotwork command line, the npm package `@buun_group/plotwork`.

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Send a file as the new source of a tab, against the version it was pulled at; a conflict is explained, never overwritten. |
| How do I run it? | `npx -y @buun_group/plotwork@0.2.0 board push`, or `plotwork board push` once the package is installed. |
| What does it write? | The sidecar, with the new version, after a push the board kept. |
| 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 push --help` |

## Synopsis

```sh
plotwork board push <file> | <board> <tab> <file> [--revision <id>] [--force] [--json]
```

## What it does

Checks the file on this machine, then sends its whole source as the tab's new version, against the version its sidecar recorded. With only `<file>`, the board, tab and revision come from the sidecar. A file that has not changed since it was pulled sends nothing.

When someone changed the tab since that version, the board refuses the push with `diagram.version_conflict`. The command then prints who changed what since, how the file differs from the tab now, and what to do: pull and redo the change, send it as edits with `board edit` (which the board rebases), or `--force`, which replaces the board's version with the file. The tab's history keeps the version it replaced.

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. |
| `--force` | Off | Send against the tab's current version, replacing whatever changed since the file was pulled, or a file that was never pulled. |
| `--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

Send a pulled file back to its tab.

```sh
plotwork board push docs/payments.diagram
```

Replace the tab's source with a file that was never pulled.

```sh
plotwork board push Checkout Payments docs/payments.diagram --force
```

## Exit codes

| Code | When |
|---|---|
| `0` | The tab has the file's source, or the file had not changed. |
| `1` | The file has errors (nothing is sent), the tab changed since the file was pulled (a conflict, explained), or the API refused it. |
| `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 has no sidecar for the tab and `--force` was not given. |

## 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 |