147 lines
5.4 KiB
Markdown
147 lines
5.4 KiB
Markdown
# 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.
|