# Render Pkl configuration

> Generate JSON, YAML, and PCF from Pkl configuration files for applications, deployment tools, and CI.

Coming in Elide 1.6.3. Evaluate a `.pkl` or `.pcf` file directly and send its rendered output to stdout.
Use this to generate application configuration, feed deployment tools, or inspect a configuration before committing it.
No Elide project is required.

## Generate JSON or YAML

Start with `config.pkl`:

```pkl
service = "api"
port = 8080
```

Choose the format your application consumes and redirect the result to a file:

```shell
elide --format=json config.pkl > config.json
elide --format=yaml config.pkl > config.yaml
```

The JSON output contains `service` and `port` with the same values and types. The explicit `run` command works too:

```shell
elide run --format json config.pkl
```

Both `.pkl` and `.pcf` inputs accept the same options. For example, convert an existing PCF configuration to JSON:

```shell
elide --format=json config.pcf > config.json
```

## Choose an output format

| Option | Output | Typical use |
| --- | --- | --- |
| `--format=json` | JSON | Application settings and JSON-consuming tools |
| `--format=yaml` | YAML | Deployment configuration |
| `--format=pcf` | Pkl Configuration Format | Inspect evaluated configuration in Pkl notation |
| No `--format` | The module's configured output; PCF by default | Honor a module's own output definition |

TOML output is not supported. An unsupported format fails with exit code `2`.

## Share configuration across files

Relative imports resolve from the input file, so a configuration can reuse nearby defaults even when invoked
from another directory. For example, place `defaults.pkl` and `config.pkl` together under `config/`:

```pkl
// defaults.pkl
port = 8080
```

```pkl
// config.pkl
import "defaults.pkl"

service = "api"
port = defaults.port
```

From the repository root, render the configuration with:

```shell
elide --format=json config/config.pkl
```

## Use the output in scripts and CI

Stdout contains only the rendered document; diagnostics and evaluation errors go to stderr. No `--quiet` flag is
needed for redirection or pipelines. For example, inspect a property with `jq` installed:

```shell
elide --format=json config.pkl | jq '.port'
```

An evaluation failure exits with code `1` and writes no rendered content to stdout. To update a file atomically,
use `--out` rather than shell redirection:

```shell
elide --format=json --out config.json config.pkl
```

`--out config.json` writes a temporary file in the destination directory and atomically replaces `config.json`
only after evaluation and writing succeed. Failures leave the existing file unchanged and exit nonzero. The
destination directory must exist and support atomic replacement. Relative paths resolve from your working directory.

Use `--out -` to explicitly select stdout:

```shell
elide --format=json --out - config.pkl
```

Document rendering rejects `--sandbox` and `--limit`; those execution controls do not apply to this command.
For all command options, see the [CLI reference](https://elide.help/docs/cli-references). To read a README or runbook in the same
terminal, see [Markdown in the terminal](https://elide.help/docs/terminal-markdown).