# 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.