Retire the legacy CLI and document native operator workflows

This commit is contained in:
2026-11-20 05:08:40 +00:00
parent 10387d4aea
commit bd7136ceeb
52 changed files with 846 additions and 7067 deletions

View File

@@ -0,0 +1,95 @@
# Migrate To The Native CLI
This guide covers Scriptorium's breaking CommandKit-native CLI cutover. It does
not select a release version or change historical release notes. The
[CLI reference](../cli.md) owns current syntax, streams, and statuses;
[configuration](../config.md) owns source discovery and settings.
The earlier [PromptKit upgrade](upgrading-promptkit.md) covers framework formats,
not a compatibility layer for this interface.
## Replace Commands And Selections
| Former interface | Current interface |
| --- | --- |
| `run --prompt ID` / `--prompt-id` | `run ID`; exactly one positional prompt ID. |
| `render --prompt ID` | `promptkit show prepared ID`. |
| `inspect prompt --prompt ID` | `promptkit show prompt ID`. |
| `inspect profile --profile ID` | `promptkit show profile ID`. |
| `inspect configuration ...` | Native `config ... --scope promptkit`. |
| Application `config ...` | Native `config ... --scope app` (the default scope), including diff. |
| `--config-overlay` | `--overlay NAME`; a native overlay name, not an arbitrary path. |
| `--input NAME=PATH` | `--input-file NAME=PATH`; `--input` now means literal text. |
| `--llm-base-url` | `--endpoint` (canonical `--llm-endpoint`). |
| Duration-valued `--timeout` | Integer `--timeout-seconds` for each generation attempt. |
| `--out` / output-file flags | Caller stdout redirection. |
| `--execution-report` | `--report PATH` with native result rendering. |
Prefer native short aliases such as `--profile`, `--var`, `--input-text`, and
`--input-file`; canonical `--llm-*` spellings remain available.
There is no duplicate prompt flag, direct backend-ID override, or retained
`--profile-id` alias on generation.
Repeat mappings rather than comma-separating them. The first equals sign splits
each mapping; commas and later equals signs are literal. Input text/file
occurrences share native last-occurrence precedence.
## Migrate Application Configuration
Replace the source-selector list and top-level schema directory with
`promptkit.configuration` and `promptkit.schema_dir`.
The [maintained example](../../examples/config.yml) selects a separate framework
entry file that imports prompt/profile/backend definitions through native
ConfigKit composition. No source/schema CLI flags or compatibility conversion
remain. Do not embed framework definitions inside the application section.
Discovery now uses native cwd, user-config, home, then Unix-system presets and
their filename conventions. It is no longer limited to the two former
`config.yml` paths. Set an explicit config path when migrating unattended jobs.
Overlays remain native name selections. Application-scope native `--set` records
retain conflict rejection; order does not make duplicate paths authoritative.
There are no custom source/schema/HTTP selectors under `config`.
## Capture Artifacts And Reports
For an artifact file plus full native report, from the repository root:
```sh
scriptorium run generic.markdown_summary --config examples/config.yml \
--input-file transcript=examples/fixtures/transcript.md \
--input-file glossary=examples/fixtures/glossary.yml \
--report run-result.json --report-format json > summary.md
```
This generation example contacts the configured provider. Use native prepared
preview instead when only checking inputs/settings.
Main automatic/text output is the artifact alone, with no added newline.
Main JSON/YAML is the native result; artifact bytes use native structured
serialization. Separate reports contain that full native result, not the old
observer-derived metadata shape. `--report-format` independently chooses
text/YAML/JSON; omission leaves the format unset for native automatic rendering
(currently YAML for structured values). Extensions do not select formats.
Omit quiet to capture main output, including redirected stdout. Quiet still
allows an explicitly requested report file. Reports are available only when a
result is returned; resultless failures do not replace an existing report.
Partial delivery can leave one or both destinations written. Keep paths separate
and check status/diagnostics before treating files as fresh.
## Adjust Status And Sensitivity Handling
Completed generated-content validation failure is now domain status 4, not the
old status 2. Native usage/invalid-configuration input is 2, diff-check
differences are 3, and operational failures are 1. Presentation/file failures
can change success into failure while preserving an already nonzero domain
classification. The [CLI status table](../cli.md#server-and-statuses) owns details.
Native prompt inspection includes messages; prepared reports include rendered
content; full run reports include generated content and metadata. Framework
classified-field redaction does not make arbitrary report data safe to expose.
Requirements discovery is separate from validation/preparation: it can run
before artifacts exist, and a partial report may succeed. Read its native
completeness/issue fields. Smoke tests are explicit provider operations, not
startup checks. See [subprocess guidance](../integrations/subprocess.md) for
stream capture, cancellation, and caller responsibilities.