205 lines
8.6 KiB
Markdown
205 lines
8.6 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.
|
|
|
|
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. |
|
|
|
|
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. |
|
|
| `--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. |
|
|
| `--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. |
|
|
|
|
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-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.9.0/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
|
|
|
|
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.
|
|
|
|
## `scriptorium render`
|
|
|
|
```text
|
|
scriptorium render [flags]
|
|
```
|
|
|
|
`--prompt <id>` is required. The following optional flags are supported:
|
|
`--config`, `--prompt-dir`, `--profile-dir`, `--prompt-version`, `--profile`,
|
|
`--input`, `--var`, `--out`, `--llm-base-url`,
|
|
`--model`, `--api-key-env`, `--temperature`, `--max-tokens`, `--top-p`,
|
|
`--reasoning-effort`, `--session-id`, `--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.
|
|
The same session and reasoning inheritance, replacement, and clearing behavior
|
|
also applies.
|
|
`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).
|
|
|
|
## `scriptorium inspect prompt`
|
|
|
|
```text
|
|
scriptorium inspect prompt --prompt ID [--prompt-version VERSION]
|
|
[--config PATH] [--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] [--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.
|
|
|
|
## 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.
|