234 lines
7.8 KiB
Markdown
234 lines
7.8 KiB
Markdown
# 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`
|