187 lines
11 KiB
Markdown
187 lines
11 KiB
Markdown
# CLI Reference
|
|
|
|
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
|
|
|
|
```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
|
|
```
|
|
|
|
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 |
|
|
| --- | --- |
|
|
| `--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. |
|
|
|
|
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.
|
|
|
|
### Results And Separate Reports
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
`--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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## Application Configuration Inspection
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## Framework Configuration Inspection
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## Discovery, Preview, And Explicit Smoke Testing
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## Server And Statuses
|
|
|
|
`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).
|
|
|
|
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 | 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. |
|
|
|
|
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.
|
|
|
|
[native-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md
|