Command reference

plotwork import-source

Turn SQL, OpenAPI, Terraform, Compose, CSV, a git log, and more into Plotwork source. It is a command of the Plotwork command line, the npm package @buun_group/plotwork.

TL;DR

Question	Answer
What does it do?	Turn SQL, OpenAPI, Terraform, Compose, CSV, a git log, and more into Plotwork source.
How do I run it?	`npx -y @buun_group/plotwork@0.1.0-beta.13 import-source`, or `plotwork import-source` once the package is installed.
What does it write?	The source, only with `--out`.
Does it use the network?	No. It reads and writes files on this machine only.
Does it read the repository settings?	No.
How do I read this in a terminal?	`plotwork import-source --help`

Synopsis

plotwork import-source <format> <file|folder> [--out <file>] [--title <text>] [--format text|json] [--view endpoints|map|sequence|git|timeline|context|container|component] [--operation <id>] [--chart auto|xychart|pie|sankey|treemap|matrix] [--tables <names>] [--tags <tags>] [--paths <prefixes>] [--group-by module|network|file|owner] [--var-file <files>] [--root <folder>]

What it does

Reads a file of another format, or every file of a folder, and prints a Plotwork diagram of it. The formats are sql, prisma, drizzle, openapi, terraform, terraform-plan, bicep, arm, pulumi, cloudformation, cdk, compose, kubernetes, helm, kustomize, backstage, structurizr, asyncapi, github-actions, gitlab-ci, azure-pipelines, csv, json, tree, git-log.

Every diagnostic is printed with the line of the file it points at, and says what was left out. A file too big for one picture is split in parts: with --out, each part is written beside it as name.2.diagram and so on. Nothing in the file is run, and nothing is fetched.

Options

Option	Default	What it does
`--out <file>`	standard output	Write the source to a file, and the parts of a split import beside it.
`--title <text>`	a title from the file	The title of the diagram.
`--format text\|json`	`text`	`json` prints the whole result: the source, the parts, the diagnostics, and the validation.
`--view endpoints\|map\|sequence\|git\|timeline\|context\|container\|component`	the usual picture of the format	Which picture of a format that has several; for a Structurizr workspace, the C4 level.
`--operation <id>`	Off	The OpenAPI operation a sequence view follows.
`--chart auto\|xychart\|pie\|sankey\|treemap\|matrix`	`auto`	The chart a CSV or JSON table becomes.
`--tables <names>`	every table	Only these tables of a schema, by name or prefix, separated by commas, such as `users,org_*`.
`--tags <tags>`	every endpoint	Only the endpoints of an OpenAPI document with these tags, separated by commas.
`--paths <prefixes>`	every endpoint	Only the endpoints under these paths, separated by commas, such as `/orders`.
`--group-by module\|network\|file\|owner`	`module`	How infrastructure resources, or a Backstage catalog (`owner`), are framed.
`--var-file <files>`	Off	Variables files to apply, separated by commas: `.tfvars`, `.bicepparam`, ARM parameters, or `Pulumi.<stack>.yaml`.
`--root <folder>`	each root is drawn, as a part of its own	The root module, deployment, or program to draw when the folder holds several, by its folder or the end of it; for a Structurizr workspace, the system or container a view is about.

Examples

Draw a database schema from its SQL.

plotwork import-source sql schema.sql --out schema.diagram

Draw the endpoints of one tag of an API.

plotwork import-source openapi openapi.yaml --tags orders

Draw a Terraform folder with the values of one environment.

plotwork import-source terraform infra --var-file env/prod.tfvars --out infra.diagram

Exit codes

Code	When
`0`	The source was printed or written.
`1`	Nothing could be imported from the file.
`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 the format or a value of `--view`, `--chart`, or `--group-by` is not one it knows.

Doc	Why
Command reference	Every command of the command line
Importing from code and data	What each format becomes, and its limits
Exit codes and output formats	What every code and format means