Retire the legacy CLI and document native operator workflows
This commit is contained in:
95
docs/consumers/upgrading-cli.md
Normal file
95
docs/consumers/upgrading-cli.md
Normal 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.
|
||||
Reference in New Issue
Block a user