# plotwork import-source

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

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

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

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

Draw the endpoints of one tag of an API.

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

Draw a Terraform folder with the values of one environment.

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

## See also

| Doc | Why |
|---|---|
| [Command reference](https://docs.plotwork.dev/cli/commands.md) | Every command of the command line |
| [Importing from code and data](https://docs.plotwork.dev/importing-from-code-and-data.md) | What each format becomes, and its limits |
| [Exit codes and output formats](https://docs.plotwork.dev/cli/exit-codes-and-output.md) | What every code and format means |