96 lines
5.1 KiB
Markdown
96 lines
5.1 KiB
Markdown
|
|
# 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.
|