158 lines
5.5 KiB
Markdown
158 lines
5.5 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 and formats the prompt without calling an LLM.
|
|
|
|
## Command Overview
|
|
|
|
- `scriptorium run`: prepare prompt, call the configured LLM, write generated output, print a run summary.
|
|
- `scriptorium render`: prepare prompt only; write prepared-run output as `text` or `json`.
|
|
- `scriptorium serve`: start the HTTP server.
|
|
|
|
Integration references:
|
|
|
|
- [HTTP contract](integrations/http-api.md)
|
|
- [Narratio subprocess contract](integrations/narratio.md)
|
|
|
|
## Common Argument Rules
|
|
|
|
- `--config` is supported by `run`, `render`, and `serve`.
|
|
- `run` and `render` require:
|
|
- `--prompt`
|
|
- at least one `--input`
|
|
- an effective `prompt_dir` and `profile_dir` (from flags or config)
|
|
- `serve` requires an effective `prompt_dir` and `profile_dir` (from flags or config).
|
|
- Positional arguments are rejected.
|
|
- Prompt cache control is configured in prompt YAML (`messages[].cache_control`), not with CLI flags.
|
|
- Provider-specific `reasoning_effort` and `extra_params` are configured in profile YAML or HTTP model overrides, not with CLI flags.
|
|
|
|
## Flag Reference
|
|
|
|
### `scriptorium run`
|
|
|
|
- `--config <path>`: app config file path.
|
|
- `--prompt-dir <dir>`: prompt definition directory.
|
|
- `--profile-dir <dir>`: profile definition directory.
|
|
- `--schema-dir <dir>`: schema base directory for `json_schema` validation.
|
|
- `--prompt <id>`: prompt ID to execute. Required.
|
|
- `--prompt-id <id>`: deprecated alias for `--prompt`.
|
|
- `--profile <id>`: explicit profile override.
|
|
- `--profile-id <id>`: deprecated alias for `--profile`.
|
|
- `--input name=path`: input mapping (repeatable, comma-separated accepted).
|
|
- `--var name=value`: template variable mapping (repeatable, comma-separated accepted).
|
|
- `--out <path>`: write artifact body to 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 (Go duration syntax, for example `30s`, `2m`).
|
|
|
|
Numeric runtime override flags are presence-aware:
|
|
|
|
- omitted numeric flags preserve the selected profile/default value
|
|
- explicit zero values override the selected profile/default value (`--temperature 0`, `--max-tokens 0`, `--top-p 0`, `--timeout 0s`)
|
|
|
|
### `scriptorium render`
|
|
|
|
- Supports the same flags as `run`, except:
|
|
- no `--schema-dir` flag.
|
|
- Adds:
|
|
- `--format text|json`: prepared-run output format.
|
|
|
|
Notes:
|
|
- `render` still resolves profile and runtime settings.
|
|
- `render` still validates that `api_key_env` exists if the selected profile or overrides require it.
|
|
|
|
### `scriptorium serve`
|
|
|
|
- `--config <path>`: app config file path.
|
|
- `--addr <listen-address>`: HTTP listen address.
|
|
- `--prompt-dir <dir>`: prompt definition directory.
|
|
- `--profile-dir <dir>`: profile definition directory.
|
|
- `--schema-dir <dir>`: schema base directory for `json_schema` validation.
|
|
|
|
Notes:
|
|
- `serve` does not accept runtime model override flags such as `--model` or `--llm-base-url`.
|
|
|
|
## Input And Variable Syntax
|
|
|
|
- `--input name=path` maps prompt input names to local file paths.
|
|
- `--var name=value` maps template variable names to values.
|
|
- If a prompt defines `session_id: "{{ .session_id }}"`, pass the OpenRouter sticky-routing value with `--var session_id=<value>`.
|
|
- Both flags can be repeated.
|
|
- Both flags also support comma-separated batches, for example:
|
|
- `--input transcript=./t.md,glossary=./g.yml`
|
|
- `--var session_id=42,session_date=2026-05-04`
|
|
|
|
## Output Behavior
|
|
|
|
`run`:
|
|
- Writes generated artifact content to stdout by default.
|
|
- Writes generated artifact content to `--out` when provided.
|
|
- Prints run summary metadata to stderr on success.
|
|
- Appends `cached_tokens=<n> cache_write_tokens=<n>` to the summary only when the provider reports non-zero cache usage.
|
|
- 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 line.
|
|
|
|
`serve`:
|
|
- Logs startup and server errors to stderr.
|
|
|
|
## Exit Codes
|
|
|
|
- `0`: success.
|
|
- `1`: runtime/parse/config/load/render/generation/output-write error.
|
|
- `2`: `run` completed, output was generated, but validation status is `failed`.
|
|
|
|
When `run` exits `2`, output may already be written to stdout or `--out`.
|
|
|
|
## Common Workflows
|
|
|
|
Render prompt inputs and template 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 profile override 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 explicit config:
|
|
|
|
```bash
|
|
go run ./cmd/scriptorium serve --config ./examples/config.yml
|
|
```
|
|
|
|
Copyable example script:
|
|
|
|
- `examples/render-markdown-summary.sh`
|