Retire the legacy CLI and document native operator workflows
This commit is contained in:
487
docs/cli.md
487
docs/cli.md
@@ -1,377 +1,186 @@
|
||||
# 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.
|
||||
Scriptorium uses CommandKit v0.7.0, ckconfig v0.9.0, and ckprompt v0.10.0.
|
||||
This document owns application invocation and delivery behavior. The pinned
|
||||
[upstream CLI contract][native-cli] owns standard family grammar and reports.
|
||||
[Configuration](config.md) owns discovery, settings, and source composition;
|
||||
the [HTTP API](api.md) owns the service contract.
|
||||
Existing callers should read the [CLI migration guide](consumers/upgrading-cli.md).
|
||||
|
||||
## 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 resolved profile without model execution.
|
||||
- `scriptorium inspect configuration`: validate or inspect Promptkit's captured framework configuration.
|
||||
- `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 command families accept `--config <path>` and `--config-overlay <name>`;
|
||||
positional arguments are rejected. `--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 absent-main behavior. `run`, `render`, `serve`, `inspect prompt`,
|
||||
`inspect profile`, and `inspect configuration` accept repeated
|
||||
`--promptkit-source <path>` flags and `--schema-dir <dir>` where applicable.
|
||||
They replace the configured source sequence in flag order. `--prompt-dir` and
|
||||
`--profile-dir` are no longer supported; use `promptkit_sources` in application
|
||||
configuration or the repeated source flags. Application `config` commands
|
||||
remain independent of framework source loading. 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. |
|
||||
| `--promptkit-source <path>` | PromptKit source file or directory; repeat to select ordered sources. |
|
||||
| `--schema-dir <dir>` | Schema base-directory override. |
|
||||
| `--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://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/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 identified by PromptKit as an
|
||||
operation timeout exits 1 with a safe deadline diagnostic; a completed invalid
|
||||
output still exits 2. Synchronous work may not stop immediately.
|
||||
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 and profile IDs are passed unchanged, including collection-qualified
|
||||
IDs. The removed `--prompt-version` flag is rejected. `--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`, repeatable `--promptkit-source`, `--schema-dir`, `--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.
|
||||
|
||||
To render from independently maintained collection checkouts:
|
||||
|
||||
```bash
|
||||
go run ./cmd/scriptorium render --config ./examples/config.discovery.yml \
|
||||
--prompt support/answer --profile support/fast \
|
||||
--input transcript=./examples/fixtures/transcript.md
|
||||
```
|
||||
|
||||
The [discovery example](../examples/discovery/framework.yml) also provides
|
||||
`review/answer`; see [configuration discovery](config.md#collection-checkout-discovery).
|
||||
|
||||
## `scriptorium serve`
|
||||
|
||||
```text
|
||||
scriptorium run PROMPT_ID [flags]
|
||||
scriptorium serve [flags]
|
||||
scriptorium config scopes
|
||||
scriptorium config validate|show|sources|explain|diff [flags]
|
||||
scriptorium promptkit list prompts|profiles|backends|namespaces|collections [flags]
|
||||
scriptorium promptkit show prompt|profile|backend ID [flags]
|
||||
scriptorium promptkit requirements show|validate PROMPT_ID [flags]
|
||||
scriptorium promptkit show prepared PROMPT_ID [flags]
|
||||
scriptorium promptkit test KIND [flags]
|
||||
scriptorium help [COMMAND ...]
|
||||
scriptorium version
|
||||
scriptorium completion bash|zsh|fish
|
||||
```
|
||||
|
||||
Optional flags:
|
||||
Native help is also available with `--help`. Help, version, scope discovery,
|
||||
and static completion do not load configuration or contact a provider.
|
||||
Version/revision metadata is supplied by the build; ordinary builds identify
|
||||
themselves as `dev` with no revision. Release build mechanics belong to the
|
||||
[release procedure](release.md).
|
||||
|
||||
Commands that consume configuration accept `--config PATH` and `--overlay NAME`.
|
||||
An explicitly empty config value remains explicit; overlay names follow
|
||||
[ConfigKit selection](config.md#explicit-imports-and-selected-overlays).
|
||||
There are no source/schema convenience flags or legacy command aliases.
|
||||
Native shared `--format`, `--quiet`, `--verbose`, `--debug`, and progress
|
||||
controls retain their upstream meanings. Diagnostics use stderr, not stdout.
|
||||
Verbose exposes emitted Info and Warning messages without changing result bytes.
|
||||
|
||||
## Generation
|
||||
|
||||
`run` requires exactly one positional prompt ID. It has no duplicate prompt
|
||||
flag or direct backend-selection flag; choose a profile for backend routing.
|
||||
It uses these native bindings, with the preferred aliases below. Canonical
|
||||
spellings prepend `llm-` (for example, `--llm-profile`).
|
||||
|
||||
| Preferred flags | Meaning |
|
||||
| --- | --- |
|
||||
| `--profile ID`, `--session-id ID` | Profile selection and optional non-secret session context. |
|
||||
| `--var KEY=VALUE` | Repeatable caller-variable mappings. |
|
||||
| `--input-text NAME=TEXT`, `--input NAME=TEXT` | Repeatable literal input mappings; `--llm-input` is also a literal-text alias. |
|
||||
| `--input-file NAME=PATH` | Repeatable file references. |
|
||||
| `--endpoint URL`, `--model NAME` | Native endpoint/model overrides. |
|
||||
| `--temperature N`, `--max-tokens N`, `--top-p N` | Presence-aware numeric overrides, including zero. |
|
||||
| `--timeout-seconds N` | Integer per-attempt generation timeout; zero disables that deadline, not caller cancellation or the transport cap. |
|
||||
| `--reasoning-effort VALUE`, `--service-tier VALUE` | Native provider controls; an explicit empty reasoning value is preserved. |
|
||||
| `--api-key-env NAME` | Credential environment-variable name, never raw key bytes. |
|
||||
| `--extra-params JSON` | Native JSON-object provider parameters. |
|
||||
| `--transient-retries N` | Request retry override; omission leaves the engine default. |
|
||||
| `--prompt-namespace NAME`, `--profile-namespace NAME`, `--backend-namespace NAME` | Independent native namespace views. Qualified resource IDs remain exact; stored references are not rewritten. |
|
||||
|
||||
Mappings split at the first `=`; commas and subsequent equals signs are literal.
|
||||
Repeat flags for multiple mappings. The last text/file occurrence for the same
|
||||
input wins in command-line order. PromptKit validates selected definitions,
|
||||
inputs, namespaces, provider settings, and credential requirements; Scriptorium
|
||||
does not add an execution-readiness preflight or configurable default namespace.
|
||||
Native string/pointer override semantics remain upstream-owned.
|
||||
|
||||
Application-owned generation controls:
|
||||
|
||||
| Flag | Meaning |
|
||||
| --- | --- |
|
||||
| `--config <path>` | Application configuration file. |
|
||||
| `--config-overlay <name>` | Selected application configuration overlay. |
|
||||
| `--addr <listen-address>` | HTTP listen-address override. |
|
||||
| `--promptkit-source <path>` | PromptKit source file or directory; repeat to select ordered sources. |
|
||||
| `--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. |
|
||||
| `--run-timeout DURATION` | Go duration passed unchanged to PromptKit's operation budget. Positive values cover engine preparation/execution, including cooperative waits and repairs. Zero, omission, and negative values add no budget. Parsing, configuration/engine setup, and delivery are outside it. |
|
||||
| `--report PATH` | Additionally write the returned native result to a separate file. |
|
||||
| `--report-format text\|yaml\|json` | Explicit separate-report format; omission leaves native automatic rendering selected. |
|
||||
|
||||
`serve` accepts no runtime model override flags. HTTP request fields, response
|
||||
schemas, and error codes are defined in the [HTTP API reference](api.md).
|
||||
The operation budget is independent of the integer per-attempt timeout.
|
||||
Earlier parent cancellation/deadlines still apply. Cancellation is cooperative;
|
||||
synchronous work that ignores context cannot be forcibly interrupted.
|
||||
|
||||
## `scriptorium inspect prompt`
|
||||
### Results And Separate Reports
|
||||
|
||||
```text
|
||||
scriptorium inspect prompt --prompt ID
|
||||
[--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] [--format text|json] [--out PATH]
|
||||
```
|
||||
The main report goes through the invocation reporter to stdout. Automatic/text
|
||||
output is exactly `Artifact.Body`, with no added newline, header, escaping, or
|
||||
summary. JSON/YAML output is the full native PromptKit `RunResult`, without a
|
||||
Scriptorium envelope. In native structured serialization, artifact bytes use
|
||||
the upstream representation (JSON base64), not an application text projection.
|
||||
|
||||
`--prompt` is required. Inspection uses normal configuration discovery and the
|
||||
selected Promptkit sources, defaults to text regardless of
|
||||
`defaults.render_format`, and writes to stdout unless `--out` is supplied.
|
||||
Save main output with shell redirection or the subprocess stdout destination.
|
||||
There is no `--output` or `--out` flag. Omit `--quiet` when capturing the main
|
||||
result: native quiet suppresses it even when stdout is redirected.
|
||||
|
||||
Both definition-inspection commands first construct the same engine used for
|
||||
execution from the complete selected source sequence. Construction resolves
|
||||
and validates all effective definitions, including unused ones, and captures
|
||||
referenced message-file contents and static template syntax. Invalid unused
|
||||
definitions or unreadable message resources can therefore prevent inspection.
|
||||
No prompt collection is mandatory, but selected prompts are not ignored.
|
||||
`--report` renders the same result through CommandKit without the artifact-only
|
||||
text template. Its format is independent of stdout's `--format` and the filename
|
||||
extension. Omission passes an unset format to the upstream renderer; it currently
|
||||
renders structured values as YAML in automatic/text mode. Choose an explicit
|
||||
format when required rather than relying on that upstream default.
|
||||
|
||||
Inspection does not prepare an execution request, load request-time schemas or
|
||||
artifacts, resolve credential values, reserve backend capacity, or call a model.
|
||||
Prompt inspection does not select an execution profile or render request-specific
|
||||
templates.
|
||||
Prompt output includes ID, hash, optional default profile and input metadata,
|
||||
and the output contract. Absent optional values are omitted; explicitly empty
|
||||
or zero values are retained. Captured message text is not projected.
|
||||
The requested file is written even in quiet mode. Omission creates no separate
|
||||
report. An explicitly empty path is a usage error before generation; `-` is an
|
||||
ordinary filename. New files use mode 0644 subject to umask, existing files use
|
||||
normal OS replacement behavior, and parent directories are not created.
|
||||
Render, write, and close failures are reported.
|
||||
|
||||
## `scriptorium inspect profile`
|
||||
Only a returned result is eligible for delivery. A resultless failure leaves an
|
||||
existing report untouched; it does not synthesize an invocation-error result.
|
||||
Main delivery is attempted first, then the requested report even if main
|
||||
delivery fails. Writes are nontransactional; bytes already written remain.
|
||||
Callers own redirected paths, retention, and keeping main and report destinations
|
||||
separate. A shell may truncate its redirected file before the process starts.
|
||||
|
||||
```text
|
||||
scriptorium inspect profile --profile ID
|
||||
[--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] [--format text|json] [--out PATH]
|
||||
```
|
||||
## Application Configuration Inspection
|
||||
|
||||
`--profile` is required. After the [full-source engine construction described
|
||||
above](#scriptorium-inspect-prompt), inspection selects one resolved profile
|
||||
with inheritance. `profile_model_params` contains only fields present on that
|
||||
profile; it does not fill backend defaults. `api_key_required` is a separate
|
||||
optional field. Explicit zero and empty values remain visible. Use `render`
|
||||
for request-completed model settings.
|
||||
The native `config` family defaults to `app`; select `--scope promptkit` for
|
||||
captured framework configuration or use native scope discovery/all-scope modes.
|
||||
`app` uses the actual completed ConfigKit result and does not construct an engine.
|
||||
|
||||
## Application configuration inspection
|
||||
Native `--set POINTER=JSON` is enabled only for `app`. Records go directly to
|
||||
ConfigKit: duplicate and ancestor/descendant-overlapping paths are rejected,
|
||||
not resolved by flag order. No application-specific configuration flags or
|
||||
custom `--against-*` counterparts are installed.
|
||||
|
||||
```text
|
||||
scriptorium config validate [flags]
|
||||
scriptorium config show [flags]
|
||||
scriptorium config sources [flags]
|
||||
scriptorium config explain --path JSON_POINTER [flags]
|
||||
```
|
||||
Native diff uses independent `--against-config`, `--against-overlay`, and
|
||||
supported `--against-set` selections. Omitted right-side values do not inherit
|
||||
the left side. See the [upstream contract][native-cli] for focused paths,
|
||||
metadata discovery, source IDs, findings, explanations, and detailed comparisons.
|
||||
|
||||
Each accepts `--config`, `--config-overlay`, `--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.
|
||||
## Framework Configuration Inspection
|
||||
|
||||
`validate` writes no success output; status 0 means the application configuration
|
||||
loaded and passed its own validation. It does not establish that selected
|
||||
Promptkit sources can construct an engine, credentials are present, or a
|
||||
provider is available. `show` writes ConfigKit's resolved 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. Application
|
||||
main-file and import records use the `main` layer; explicit CLI
|
||||
overrides appear as synthetic sources. Defaults-only input without overrides
|
||||
produces `[]` for `sources`.
|
||||
The `promptkit` config scope loads application settings selected by `--config`
|
||||
and `--overlay`, constructs an engine, and exposes its captured native view.
|
||||
It does not accept temporary overrides; native capability checks also apply
|
||||
when an all-scope operation requests them.
|
||||
|
||||
`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, file/import, overlay,
|
||||
CLI, normalization, and removed-value history. This is not a JSON schema or a
|
||||
byte-for-byte stable prose format. Unknown and malformed paths exit 1 without
|
||||
successful explanation output.
|
||||
Framework effective/explanation views retain native classified-field redaction,
|
||||
including history. Environment-reference names and ordinary values remain
|
||||
visible. This is not arbitrary secret detection and does not redact all prompt,
|
||||
prepared, application, or generated content. Protect reports accordingly.
|
||||
|
||||
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. Application inspection can contain paths and
|
||||
configured values; protect its output accordingly. Raw API-key values are not
|
||||
accepted by the application configuration schema.
|
||||
## Discovery, Preview, And Explicit Smoke Testing
|
||||
|
||||
## Framework configuration inspection
|
||||
Inventories retain native defaults and `--namespace`/`--all-namespaces` filters.
|
||||
Named inspections expose native prompt messages and profile/backend values;
|
||||
prepared preview exposes rendered content, not a summary projection.
|
||||
|
||||
```text
|
||||
scriptorium inspect configuration validate [flags]
|
||||
scriptorium inspect configuration show [flags]
|
||||
scriptorium inspect configuration sources [flags]
|
||||
scriptorium inspect configuration explain --path JSON_POINTER [flags]
|
||||
```
|
||||
Requirements discovery works before input artifacts exist and without schema
|
||||
loading, credential resolution, message rendering, or provider access. It still
|
||||
loads configuration and captured message resources. Reports preserve exact names,
|
||||
metadata, variable presence (including empty values), completeness, and issue
|
||||
codes. Partial discovery may succeed with status zero; completeness is not
|
||||
binding satisfaction or execution readiness. Concrete validation and preview
|
||||
keep their native preparation-time prerequisites and make no generation call.
|
||||
|
||||
Each operation accepts `--config`, `--config-overlay`, repeatable
|
||||
`--promptkit-source`, and `--schema-dir`. These flags select the application
|
||||
settings and framework sources; positional arguments, `--format`, and `--out`
|
||||
are not accepted. Unlike `config validate`, framework `validate` constructs
|
||||
the Promptkit engine and validates all effective definitions, including
|
||||
unused ones. It writes nothing on success and does not prepare a request,
|
||||
resolve a credential, or contact a provider.
|
||||
Smoke-test kinds are `reachability`, `authentication`, `text_inference`,
|
||||
`structured_output`, or `all`, with native aliases as documented upstream.
|
||||
These explicit commands may contact providers and incur cost. Their presence
|
||||
does not add a startup/provider probe. Read the native findings: unsuccessful or
|
||||
unsupported checks are not automatically invocation failures.
|
||||
|
||||
`show` writes Promptkit's native effective YAML, an inspection snapshot rather
|
||||
than a promised reloadable file. `sources` writes a
|
||||
newline-terminated JSON array in captured source order. Each source record has
|
||||
`id`, `label`, `layer`, `kind`, and `underlay_index`, plus `path` when available
|
||||
and `imported_from` for imported sources. That nested object has `source_id`,
|
||||
`line`, and `column`. Values and output structure are a projection of the
|
||||
captured Promptkit view, not Scriptorium's application-source records.
|
||||
## Server And Statuses
|
||||
|
||||
`explain` requires an explicitly supplied `--path` in ConfigKit JSON Pointer
|
||||
syntax; `--path ''` selects the root. For example,
|
||||
`/collections/support/profiles/0/model` addresses the first support profile's
|
||||
model in the captured list. Escape `/` as `~1` and `~` as `~0`; dots in a key
|
||||
remain literal. Malformed and unknown pointers exit 1 without a successful
|
||||
report. Explanation prose is native and is not a stable machine-readable
|
||||
format.
|
||||
`serve` accepts configuration selection and presence-aware HTTP controls:
|
||||
`--addr`, `--artifact-root`, `--max-request-bytes`, `--max-artifact-bytes`,
|
||||
and `--max-response-bytes`. It has no generation request controls. Values and
|
||||
defaults belong to [configuration](config.md).
|
||||
|
||||
Framework `show` and `explain` use Promptkit's native redaction for its
|
||||
classified credential-shaped provider fields, including historical values.
|
||||
Environment-variable reference names and ordinary provider parameters remain
|
||||
visible. Arbitrary prompt or provider content is not classified as secret by
|
||||
name inspection, so treat these reports as sensitive. This redaction policy is
|
||||
limited to framework configuration reports; it does not add redaction to
|
||||
`inspect profile` or prepared-run output. Credentials are not resolved by any
|
||||
of these inspection operations. Promptkit owns detailed field and source
|
||||
semantics; see its tagged [format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).
|
||||
|
||||
Warnings and errors go to stderr. Successful `validate` writes nothing to
|
||||
stdout; successful `show`, `sources`, and `explain` write their reports there.
|
||||
Parse, load, path, and output failures exit 1. A native writer error may leave
|
||||
partial output.
|
||||
|
||||
## 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:
|
||||
Interrupt/SIGTERM cancels the invocation context. The server closes its listener
|
||||
and active connections; canceled shutdown returns operational status, with no
|
||||
graceful-drain deadline or guarantee that context-ignoring work has finished.
|
||||
|
||||
| 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. |
|
||||
| 0 | Native success, subject to successful presentation/delivery. |
|
||||
| 1 | Operational failure, including lookup/preparation/generation/capacity, cancellation/timeouts, unclassified load errors, and delivery failure for an otherwise successful run. |
|
||||
| 2 | Native usage/declaration-input errors, or configuration errors classified as invalid input by native diagnostic evidence. |
|
||||
| 3 | Native `config diff --check` found differences. |
|
||||
| 4 | Completed generation returned `ValidationFailed`; artifact and native result remain deliverable. |
|
||||
|
||||
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).
|
||||
Native finalization handles presentation errors: success/usage become operational;
|
||||
an already nonzero domain outcome retains its classification/status. A report-file
|
||||
failure preserves completed-validation status 4 while adding its explanation and
|
||||
cause. An operational failure to perform validation is status 1, not status 4.
|
||||
JSON selection does not turn failures into a separate JSON error envelope.
|
||||
|
||||
## 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.
|
||||
[native-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md
|
||||
|
||||
Reference in New Issue
Block a user