Files
scriptorium/docs/consumers/upgrading-cli.md

5.1 KiB

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 owns current syntax, streams, and statuses; configuration owns source discovery and settings. The earlier PromptKit upgrade 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 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:

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 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 for stream capture, cancellation, and caller responsibilities.