# CLI Reference

This is the canonical contract for invoking Scriptorium. Configuration discovery,
precedence, directories, profiles, and schemas are defined in the
[configuration reference](config.md). The [HTTP API reference](api.md) owns
service request and response behavior.

## 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 a request without calling an LLM.

## Commands

- `scriptorium run`: prepare a prompt, call the configured LLM, and write the
  generated artifact.
- `scriptorium render`: prepare a prompt and write prepared-run output.
- `scriptorium serve`: start the HTTP server.

All commands accept `--config <path>` and reject positional arguments. An
effective `prompt_dir` is required for every command. Supply it through the
configuration contract or the command's `--prompt-dir` flag.

## `scriptorium run`

```text
scriptorium run [flags]
```

Required flags:

| Flag | Meaning |
| --- | --- |
| `--prompt <id>` | Prompt ID to execute. |
| `--input name=path` | Input file mapping; repeat or use comma-separated mappings. |

Optional flags:

| Flag | Meaning |
| --- | --- |
| `--config <path>` | Application configuration file. |
| `--prompt-dir <dir>` | Prompt-definition directory override. |
| `--profile-dir <dir>` | Custom profile-directory override. |
| `--schema-dir <dir>` | Schema base-directory override. |
| `--profile <id>` | Execution-profile override. |
| `--var name=value` | Template-variable mapping; repeat or use comma-separated mappings. |
| `--out <path>` | Write generated content to this 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 maximum-token override. |
| `--top-p <float>` | Runtime top-p override. |
| `--timeout <duration>` | Runtime timeout override using Go duration syntax. |

Deprecated aliases: `--prompt-id` for `--prompt`, and `--profile-id` for
`--profile`.

Omitted numeric runtime flags preserve the selected effective value; explicit
zero values override it. `--timeout 0s` disables the outbound HTTP-client
timeout. CLI durations are converted to whole seconds by truncation toward
zero, so any duration whose absolute value is below one second becomes an
explicit zero-second override.

There is no raw API-key flag. Use `--api-key-env`.

## `scriptorium render`

```text
scriptorium render [flags]
```

`--prompt <id>` and at least one `--input name=path` are required. The
following optional flags are supported: `--config`, `--prompt-dir`,
`--profile-dir`, `--profile`, `--var`, `--out`, `--llm-base-url`,
`--model`, `--api-key-env`, `--temperature`, `--max-tokens`, `--top-p`,
`--timeout`, and `--format text|json`. Their meanings match the corresponding
`run` flags; `--format` selects prepared-run output and otherwise uses
`defaults.render_format`.

The same deprecated aliases and numeric/timeout behavior as `run` apply.
`render` does not accept `--schema-dir`; configure `schema_dir` through the
configuration file. It resolves profiles and schemas as part of preparation but
does not call an LLM.

## `scriptorium serve`

```text
scriptorium serve [flags]
```

Optional flags:

| Flag | Meaning |
| --- | --- |
| `--config <path>` | Application configuration file. |
| `--addr <listen-address>` | HTTP listen-address override. |
| `--prompt-dir <dir>` | Prompt-definition directory override. |
| `--profile-dir <dir>` | Custom profile-directory override. |
| `--schema-dir <dir>` | Schema base-directory override. |
| `--artifact-root <dir>` | Root for HTTP `file` input references. |
| `--max-request-bytes <n>` | Maximum encoded HTTP request-body bytes; `0` disables the limit. |
| `--max-artifact-bytes <n>` | Maximum HTTP file-input artifact bytes; `0` disables the limit. |
| `--max-response-bytes <n>` | Maximum encoded HTTP response bytes; `0` disables the limit. |

`serve` accepts no runtime model override flags. HTTP request fields, response
schemas, and error codes are defined in the [HTTP API reference](api.md).

## Input And Variable Syntax

`--input name=path` maps an input name to a local file; `--var name=value`
maps a template variable to a string. Both flags can be repeated or contain
comma-separated mappings. Values may contain `=` after the first separator.
Empty names and values are rejected.

CLI inputs are file references. HTTP inline inputs are defined by the
[HTTP API reference](api.md).

## Output And Exit Behavior

- `run` writes generated content to stdout, or to `--out` when supplied, and
  writes a concise summary to stderr.
- `render` writes prepared-run output to stdout, or to `--out` when supplied,
  without a success summary.
- `serve` writes startup and server errors to stderr.

Exit statuses:

| Status | Meaning |
| --- | --- |
| `0` | Success. |
| `1` | Parse, configuration, loading, rendering, generation, output-write, or other runtime error. |
| `2` | `run` generated and wrote output, but validation failed. |

## Workflows And Examples

The [maintained render script](../examples/render-markdown-summary.sh) is a
copyable render workflow. The [HTTP request example](../examples/http-run.json)
is for a running `serve` process.