Skip to content
Studio previewSelf-host Studio locally.Run it
Kortyx
Open Kortyx on GitHub
Open navigation

Author and migrate prompts with the CLI

Updated 2 days ago • October 10, 2026

Use independently authenticated named connections for the source and destination. Connections store API URLs and environment-variable names, rather than raw keys. --project-id on kortyx connections add selects a cloud project explicitly.

kortyx connections add staging --api-url https://staging-api.example.com --api-key-env STAGING_STUDIO_KEY kortyx connections add production --api-url https://production-api.example.com --api-key-env PRODUCTION_STUDIO_KEY kortyx studio prompts list --connection staging --json kortyx studio prompts get canvas/classify-intent --connection staging --file prompt.json kortyx studio prompts validate prompt.json --json

Modify the executable JSON file, validate it, and review the hash before saving:

kortyx studio prompts update canvas/classify-intent --connection staging \ --file prompt.json --base-version 1 --expected-hash REVIEWED_HASH \ --note "Improve ambiguous intent classification" --idempotency-key SAVE_UUID --json kortyx studio prompts diff canvas/classify-intent 1 2 --connection staging --json kortyx studio prompts test canvas/classify-intent --connection staging \ --version 2 --target support-app --suite regression --case ambiguous-intent --json

edit is an alias of file-based update. versions lists identities and notes. action <file> validates and applies category, group, draft, review, policy, or asset mutations using the public action contract. archive and restore require the reviewed asset revision. Assigned prompts cannot be archived.

Plan, apply, verify

kortyx studio prompts copy canvas/classify-intent --from staging --to production \ --plan-file transfer-plan.json --json # Review the source-to-destination version/hash mapping, then apply: kortyx studio prompts apply transfer-plan.json --connection production --json

The default copy exports the selected head and its exact dependency closure. Use --version for one exact version or --history for histories, --groups for fully covered test groups, and --rename source/key=destination/key for intentional key remapping. An unrelated same-key conflict fails by default; --append explicitly allows new destination versions. Identical executable content is reused. Category paths are portable; internal category and prompt UUIDs are destination-owned. Dependency keys, versions, and hashes are remapped together, so rewritten parents receive new executable hashes while retaining their source provenance.

Plans freeze destination heads and expire after 24 hours. Applying a plan is atomic: concurrent destination edits or group conflicts reject the operation. Save the plan before applying; retrying that plan resumes the accepted operation without duplicating versions. CLI apply reads destination versions back and checks their exact hashes before reporting verification: "destination-read-back".

Copying never changes live assignments and never moves source keys, traces, eval results, or review approvals. Source identity and immutable version/hash provenance are retained. Run the imported version against the destination application's suite, then explicitly promote it under project promotion policy:

kortyx studio prompts test canvas/classify-intent --connection production \ --version DESTINATION_VERSION --target support-app --suite regression --json kortyx studio prompts promote canvas/classify-intent --connection production \ --version DESTINATION_VERSION --expected-revision 0 --json

For disconnected deployments, use export <key...> --file bundle.json and import bundle.json --plan-file transfer-plan.json. --apply combines planning and application when the mapping is already controlled by your automation.

CLI failures use nonzero exit codes. --json reports versioned errors, including prompt conflict codes, without reflecting arbitrary remote response bodies.

Editing inclusions with the CLI

Studio references appear in executable JSON as [[prompt:stable/key]]. Each key needs an exact { id, version, hash } entry in content.dependencies; use prompts get to read the child version and its hash. Keep inherited input declarations in the parent's variablesSchema, review the diff, then update and test the parent. Copy/export includes nested dependencies. Destination rename mappings rewrite both the manifest and inline tokens before recomputing hashes.

Manage release tags from the CLI

Promotion updates only live; saving a new version and editing other tags do not:

kortyx studio prompts promote canvas/classify-intent --version 9 --expected-revision 2 kortyx studio prompts tag canvas/classify-intent staging --version 10 --expected-revision 0 kortyx studio prompts untag canvas/classify-intent staging --expected-revision 1 kortyx studio prompts rollback canvas/classify-intent --version 7 --expected-revision 3

Read current tag revisions with prompts get KEY --json. Revision 0 creates a new tag; moving or removing one requires its current revision. live is reserved for promotion/rollback. Copying between connections imports immutable candidates and never copies or moves release tags automatically.