305 lines
15 KiB
Markdown
305 lines
15 KiB
Markdown
# CLI Reference
|
|
|
|
This is the canonical contract for invoking Scriptorium. Configuration discovery,
|
|
precedence, application source locations, and server settings 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.
|
|
- `scriptorium inspect prompt`: inspect one prompt definition without model execution.
|
|
- `scriptorium inspect profile`: inspect one effective profile without model execution.
|
|
- `scriptorium config validate`: validate application configuration without building an engine.
|
|
- `scriptorium config show`: show the resolved application configuration.
|
|
- `scriptorium config sources`: show the ordered configuration sources.
|
|
- `scriptorium config explain`: explain one effective or historical configuration path.
|
|
|
|
All commands accept `--config <path>` and `--config-overlay <name>` and reject
|
|
positional arguments. `--config-overlay` selects one application configuration
|
|
overlay; it is separate from `--profile`, which selects a Promptkit execution
|
|
profile. See [configuration composition](config.md#explicit-imports-and-selected-overlays)
|
|
for name, root, and no-base behavior. `run`,
|
|
`render`, `serve`, and `inspect prompt` require an effective `prompt_dir`;
|
|
`inspect profile` does not. Supply the directory through the configuration
|
|
contract or a supported `--prompt-dir` flag. Explicit application flags,
|
|
including empty values, override file settings. Configuration load diagnostics
|
|
go to stderr and exit with status 1; successful load warnings are printed once
|
|
before command work.
|
|
|
|
## `scriptorium run`
|
|
|
|
```text
|
|
scriptorium run [flags]
|
|
```
|
|
|
|
Required flags:
|
|
|
|
| Flag | Meaning |
|
|
| --- | --- |
|
|
| `--prompt <id>` | Prompt ID to execute. |
|
|
|
|
Optional flags:
|
|
|
|
| Flag | Meaning |
|
|
| --- | --- |
|
|
| `--config <path>` | Application configuration file. |
|
|
| `--config-overlay <name>` | Selected application configuration overlay. |
|
|
| `--prompt-dir <dir>` | Prompt-definition directory override. |
|
|
| `--profile-dir <dir>` | Custom profile-directory override. |
|
|
| `--schema-dir <dir>` | Schema base-directory override. |
|
|
| `--prompt-version <version>` | Optional prompt-definition version selector. |
|
|
| `--profile <id>` | Execution-profile override. |
|
|
| `--session-id <id>` | Optional direct session identifier. |
|
|
| `--input name=path` | Optional input file mapping; repeat or use comma-separated mappings. |
|
|
| `--var name=value` | Template-variable mapping; repeat or use comma-separated mappings. |
|
|
| `--out <path>` | Write generated content to this file instead of stdout. |
|
|
| `--execution-report <path>` | Write an opt-in terminal execution report as newline-terminated JSON to a separate file. |
|
|
| `--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. |
|
|
| `--reasoning-effort <value>` | Runtime reasoning-effort override. |
|
|
| `--timeout <duration>` | Runtime timeout override using Go duration syntax. |
|
|
| `--run-timeout <duration>` | Optional whole-run engine deadline using Go duration syntax; zero or omission adds no deadline, negative values are invalid. |
|
|
| `--transient-retries <integer>` | Nonnegative additional transient attempt count for this request; `0` disables additional attempts. |
|
|
|
|
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 per-attempt generation deadline
|
|
only; the caller context and configured transport cap remain active. 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. The timeout layers are defined in the
|
|
[Promptkit outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
|
|
With the built-in client, each transient retry gets a fresh generation timeout;
|
|
this flag does not limit the complete run.
|
|
`--run-timeout` keeps subsecond precision and starts immediately before engine
|
|
execution. It bounds preparation, capacity waits, retry waits, generation, and
|
|
repairs where they honor context. Parsing, engine construction, and output
|
|
writes are outside that interval. A failed run whose execution context reaches
|
|
this deadline exits 1 with a safe deadline diagnostic; a completed invalid
|
|
output still exits 2. It does not promise immediate interruption of synchronous
|
|
work.
|
|
Omitting `--transient-retries` inherits the application setting or Promptkit's
|
|
current default of two additional attempts. The flag overrides only this
|
|
request; it does not alter the configured engine. Structural repair generations
|
|
have separate transient retry budgets.
|
|
|
|
There is no raw API-key flag. Use `--api-key-env`.
|
|
|
|
`--prompt-version` is passed directly to Promptkit. When it is omitted, the
|
|
selected prompt ID must have exactly one available version. `--input` is
|
|
optional at the CLI boundary: Promptkit decides whether the selected definition
|
|
requires declared inputs or template-referenced values.
|
|
|
|
`--session-id` supplies a direct, non-secret session identifier. A nonblank
|
|
value replaces a definition-rendered session ID; an omitted or blank value lets
|
|
the definition supply one. Promptkit trims direct values and limits them to 256
|
|
Unicode code points. Use stable, non-sensitive identifiers because effective
|
|
session IDs may appear in prepared output, run metadata, and provider-facing
|
|
requests.
|
|
|
|
`--reasoning-effort` is presence-aware: omitting it inherits the selected
|
|
profile value, a nonblank value replaces that value, and
|
|
`--reasoning-effort=` explicitly clears inherited reasoning. Promptkit treats
|
|
nonblank values as provider-specific opaque strings.
|
|
|
|
### Execution report file
|
|
|
|
`--execution-report` requires a nonempty path. It is available only for `run`;
|
|
`-` is an ordinary filename. Parent directories are not created. An existing
|
|
file is replaced through ordinary file writing, without rollback or an atomic
|
|
replacement guarantee. Generated content still goes to stdout or `--out`.
|
|
Equal output/report paths, including existing paths that refer to the same
|
|
file, are rejected before execution.
|
|
|
|
The file is written after engine execution when Promptkit supplies a terminal
|
|
event, including for a failed run or invalid generated output. A failure before
|
|
invocation leaves the report path untouched. If no terminal event is supplied,
|
|
Scriptorium leaves the path untouched and emits a diagnostic; an existing file
|
|
may therefore contain an older report. Artifact output is attempted first on a
|
|
successful run, and report writing is attempted even if artifact writing fails.
|
|
Any output or report write failure exits 1; already-written output is not
|
|
undone. Without a write failure, the actual run keeps its usual exit status.
|
|
|
|
The [HTTP API reference](api.md#execution-report) defines the shared report
|
|
fields and usage-presence semantics. The file contains that JSON object followed
|
|
by a newline.
|
|
|
|
The report excludes content, credentials, URLs, headers, and raw errors, but
|
|
its identifiers can still be sensitive. The caller owns file retention and
|
|
access.
|
|
|
|
## `scriptorium render`
|
|
|
|
```text
|
|
scriptorium render [flags]
|
|
```
|
|
|
|
`--prompt <id>` is required. The following optional flags are supported:
|
|
`--config`, `--config-overlay`, `--prompt-dir`, `--profile-dir`, `--schema-dir`, `--prompt-version`, `--profile`,
|
|
`--input`, `--var`, `--out`, `--llm-base-url`,
|
|
`--model`, `--api-key-env`, `--temperature`, `--max-tokens`, `--top-p`,
|
|
`--reasoning-effort`, `--session-id`, `--timeout`, `--transient-retries`, 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.
|
|
The same session and reasoning inheritance, replacement, and clearing behavior
|
|
also applies.
|
|
`render` validates the retry override but does not generate model output or
|
|
include a retry field in prepared output.
|
|
`render` 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. |
|
|
| `--config-overlay <name>` | Selected application configuration overlay. |
|
|
| `--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).
|
|
|
|
## `scriptorium inspect prompt`
|
|
|
|
```text
|
|
scriptorium inspect prompt --prompt ID [--prompt-version VERSION]
|
|
[--config PATH] [--config-overlay NAME] [--prompt-dir DIR] [--format text|json] [--out PATH]
|
|
```
|
|
|
|
`--prompt` is required. Inspection uses normal configuration discovery and a
|
|
`--prompt-dir` override, defaults to text regardless of `defaults.render_format`,
|
|
and writes to stdout unless `--out` is supplied. It loads and normalizes the
|
|
selected definition but does not resolve a profile, load a schema, render a
|
|
template, reserve backend capacity, or call a model.
|
|
|
|
## `scriptorium inspect profile`
|
|
|
|
```text
|
|
scriptorium inspect profile --profile ID
|
|
[--config PATH] [--config-overlay NAME] [--profile-dir DIR] [--format text|json] [--out PATH]
|
|
```
|
|
|
|
`--profile` is required; built-in profiles need no prompt directory. Inspection
|
|
resolves profile inheritance and backend defaults, but never reads a credential
|
|
value, loads a prompt, reserves capacity, or calls a model. Unset provider
|
|
controls are shown as zero values when Promptkit leaves them unspecified.
|
|
|
|
## Application configuration inspection
|
|
|
|
```text
|
|
scriptorium config validate [flags]
|
|
scriptorium config show [flags]
|
|
scriptorium config sources [flags]
|
|
scriptorium config explain --path JSON_POINTER [flags]
|
|
```
|
|
|
|
Each accepts `--config`, `--config-overlay`, `--prompt-dir`, `--profile-dir`,
|
|
`--schema-dir`, `--addr`, `--artifact-root`, `--max-request-bytes`,
|
|
`--max-artifact-bytes`, and `--max-response-bytes`. These are application
|
|
configuration selectors and overrides; request, credential, backend-editing,
|
|
output-format, and output-file flags are not accepted. Positional arguments
|
|
are rejected.
|
|
|
|
`validate` writes no success output; status 0 means the application configuration
|
|
loaded and passed its own validation. It does not establish that a prompt
|
|
directory exists, credentials are present, or Promptkit can construct an
|
|
engine. `show` writes ConfigKit's resolved, redacted YAML snapshot. `sources`
|
|
writes one newline-terminated JSON array of source records in load order. Each
|
|
record has `id`, `label`, and `layer`, plus `path` when available; explicit CLI
|
|
overrides appear as synthetic sources. Defaults-only input without overrides
|
|
produces `[]` for `sources`.
|
|
|
|
`explain` requires an explicitly supplied `--path` in JSON Pointer syntax.
|
|
The empty string selects the root; `/server/addr` selects a field; `~1` and
|
|
`~0` escape `/` and `~` inside mapping keys. Numeric tokens are interpreted
|
|
according to the containing mapping or sequence. Dotted paths, file paths,
|
|
and URL fragments are not accepted. ConfigKit writes a human-readable account
|
|
of the effective value and its chronological default, base, overlay, CLI,
|
|
and normalization history, including removed historical values. This is not a
|
|
JSON schema or a byte-for-byte stable prose format. Unknown and malformed paths
|
|
exit 1 without successful explanation output.
|
|
|
|
Diagnostics and warnings go to stderr, never into successful stdout. Parse,
|
|
load, output, and diagnostic-write failures exit 1. Ordinary output writes may
|
|
leave partial data on failure. The inspection output can contain paths,
|
|
identifiers, `api_key_env` reference names, and ordinary `extra_params` values,
|
|
including displaced historical values in explanations;
|
|
protect it accordingly. Raw API-key values are not read or emitted by these
|
|
commands.
|
|
|
|
## 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. The summary includes `backend=<id>` when
|
|
Promptkit selected a backend; endpoint-only profiles omit it.
|
|
- `render` writes prepared-run output to stdout, or to `--out` when supplied,
|
|
without a success summary. Text output includes `selected_backend_id` after
|
|
`selected_profile_id` when Promptkit selected one; endpoint-only profiles
|
|
omit it.
|
|
- `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. |
|
|
|
|
A backend admission rejection is a runtime error and prints `run error: model
|
|
backend capacity is exhausted`. The HTTP capacity response is defined in the
|
|
[HTTP API reference](api.md).
|
|
|
|
## 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.
|