# CLI Reference

## Shortest Useful Command

```bash
go run ./cmd/scriptorium render \
  --config ./examples/config.yml \
  --prompt generic.markdown_summary \
  --input transcript=./examples/fixtures/transcript.md \
  --input glossary=./examples/fixtures/glossary.yml
```

`render` prepares the prompt, loads input artifacts, resolves the execution
profile, and prints the prepared request without calling an LLM.

## Command Overview

- `scriptorium run`: prepare a prompt, call the configured LLM, write generated output, and print a run summary.
- `scriptorium render`: prepare a prompt only; write prepared-run output as `text` or `json`.
- `scriptorium serve`: start the HTTP server for `POST /v1/runs`.

Canonical related references:

- [Configuration reference](config.md)
- [HTTP API reference](api.md)
- [Subprocess integration](integrations/subprocess.md)

## Common Rules

- `--config` is supported by `run`, `render`, and `serve`.
- Positional arguments are rejected.
- `run` and `render` require `--prompt`, at least one `--input`, and an effective `prompt_dir`.
- `serve` requires an effective `prompt_dir`.
- `profile_dir` is optional. Without it, only built-in profiles are available.
- If `profile_dir` is set, custom profiles override built-in profiles with the same ID.
- Prompt cache control, `session_id`, structured output, and provider-specific profile fields are configured in YAML, not with CLI flags.

Config precedence is:

1. built-in defaults
2. config file values
3. CLI flags

## Flag Reference

### `scriptorium run`

```bash
scriptorium run [flags]
```

Required through flags or config:

- `--prompt-dir <dir>`: prompt definition directory.

Required as flags:

- `--prompt <id>`: prompt ID to execute.
- `--input name=path`: input file mapping. Repeat or use comma-separated mappings.

Optional flags:

- `--config <path>`: application config file.
- `--profile-dir <dir>`: custom profile definition directory.
- `--schema-dir <dir>`: schema base directory for `json_schema` validation.
- `--profile <id>`: execution profile override. If omitted, the prompt `default_profile` is used.
- `--var name=value`: template variable mapping. Repeat or use comma-separated mappings.
- `--out <path>`: write generated artifact body to a file instead of stdout.
- `--llm-base-url <url>`: runtime endpoint override.
- `--model <name>`: runtime model override.
- `--api-key-env <name>`: runtime API-key environment variable name override.
- `--temperature <float>`: runtime temperature override.
- `--max-tokens <int>`: runtime max tokens override.
- `--top-p <float>`: runtime top-p override.
- `--timeout <duration>`: runtime timeout override using Go duration syntax, such as `30s` or `2m`.

Deprecated aliases:

- `--prompt-id <id>`: alias for `--prompt`.
- `--profile-id <id>`: alias for `--profile`.

Runtime override notes:

- Omitted numeric override flags preserve the selected profile/default value.
- Explicit zero values override the selected profile/default value.
- `--timeout 0s` disables the outbound HTTP client timeout for that request.
- There is no raw API-key flag; use `--api-key-env`.

### `scriptorium render`

```bash
scriptorium render [flags]
```

Required through flags or config:

- `--prompt-dir <dir>`: prompt definition directory.

Required as flags:

- `--prompt <id>`: prompt ID to render.
- `--input name=path`: input file mapping. Repeat or use comma-separated mappings.

Optional flags:

- `--config <path>`: application config file.
- `--prompt-dir <dir>`: prompt definition directory.
- `--profile-dir <dir>`: custom profile definition directory.
- `--profile <id>`: execution profile override.
- `--var name=value`: template variable mapping. Repeat or use comma-separated mappings.
- `--out <path>`: write prepared-run output to a file instead of stdout.
- `--llm-base-url <url>`: runtime endpoint override for the prepared request.
- `--model <name>`: runtime model override for the prepared request.
- `--api-key-env <name>`: runtime API-key environment variable name override.
- `--temperature <float>`: runtime temperature override.
- `--max-tokens <int>`: runtime max tokens override.
- `--top-p <float>`: runtime top-p override.
- `--timeout <duration>`: runtime timeout override using Go duration syntax.
- `--format text|json`: prepared-run output format. Defaults to config `defaults.render_format`, then `text`.

Deprecated aliases:

- `--prompt-id <id>`: alias for `--prompt`.
- `--profile-id <id>`: alias for `--profile`.

Notes:

- `render` resolves profiles, loads schemas for `json_schema` prompts, and validates `api_key_env`.
- `render` does not accept `--schema-dir`; use config `schema_dir` for render-time schema lookup.
- `render` does not call the LLM.

### `scriptorium serve`

```bash
scriptorium serve [flags]
```

Required through flags or config:

- `--prompt-dir <dir>`: prompt definition directory.

Optional flags:

- `--config <path>`: application config file.
- `--addr <listen-address>`: HTTP listen address.
- `--prompt-dir <dir>`: prompt definition directory.
- `--profile-dir <dir>`: custom profile definition directory.
- `--schema-dir <dir>`: schema base directory for `json_schema` validation.
- `--artifact-root <dir>`: base directory for HTTP `file` input references.
- `--max-request-bytes <n>`: maximum HTTP request body bytes; `0` disables the limit.
- `--max-artifact-bytes <n>`: maximum HTTP file artifact bytes; `0` disables the limit.
- `--max-response-bytes <n>`: maximum encoded HTTP response body bytes; `0` disables the limit.

Notes:

- `serve` does not accept runtime model override flags such as `--model` or `--llm-base-url`.
- HTTP request fields and error codes are documented in the [HTTP API reference](api.md).
- HTTP `file` input references are rejected unless an artifact root is configured.
- HTTP size-limit flags affect only `serve`.

## Input And Variable Syntax

- `--input name=path` maps prompt input names to local file paths.
- `--var name=value` maps prompt template variables to string values.
- Both flags can be repeated.
- Both flags also accept comma-separated mappings, such as `--input transcript=./t.md,glossary=./g.yml`.
- Values may contain `=` after the first separator, such as `--var note=a=b=c`.
- Empty names and empty values are rejected.

CLI `run` and `render` convert every `--input` mapping to a `file` artifact
reference. HTTP also supports `inline` input references; see [HTTP API
reference](api.md).

## Output Behavior

`run`:

- Writes generated artifact content to stdout by default.
- Writes generated artifact content to `--out` when provided.
- Prints a success summary to stderr.
- Prints errors to stderr on failure.

`render`:

- Writes prepared-run output to stdout by default.
- Writes prepared-run output to `--out` when provided.
- Does not print a success summary.

`serve`:

- Logs startup and server errors to stderr.

## Exit Codes

- `0`: success.
- `1`: parse, config, load, render, generation, output-write, or runtime error.
- `2`: `run` completed and wrote output, but validation status is `failed`.

## Common Workflows

Render prompt inputs and variables as JSON:

```bash
go run ./cmd/scriptorium render \
  --config ./examples/config.yml \
  --prompt generic.markdown_summary \
  --input transcript=./examples/fixtures/transcript.md \
  --input glossary=./examples/fixtures/glossary.yml \
  --var session_date=2026-05-04 \
  --format json
```

Run a prompt with an explicit profile and file output:

```bash
go run ./cmd/scriptorium run \
  --config ./examples/config.yml \
  --prompt generic.markdown_summary \
  --profile local-fast \
  --input transcript=./examples/fixtures/transcript.md \
  --input glossary=./examples/fixtures/glossary.yml \
  --out ./summary.md
```

Start the HTTP server with example config:

```bash
go run ./cmd/scriptorium serve --config ./examples/config.yml
```

Copyable maintained script:

- `examples/render-markdown-summary.sh`