> For the complete documentation index, see [llms.txt](https://cyr1en.gitbook.io/commandprompter/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cyr1en.gitbook.io/commandprompter/features/prompt-migration.md). # Prompt Migration Use `/cmdp migrate` to convert V2 prompt syntax inside another plugin's configuration to V3 syntax. Preview changes, apply them with an automatic backup, or restore a saved backup with `undo`. The commands require `promptpaper.migrate`, which defaults to OP and is included in `promptpaper.admin`. The same permission controls file autocomplete and undo. Use a CommandPrompter build that includes these commands. {% hint style="warning" %} Pause other writers to the selected file while migrating or restoring it. These commands change the file on disk; they do not reload the plugin that owns it. Reload that plugin after a successful migration or undo. {% endhint %} ## Preview and migrate a file For a configuration stored at `plugins/DeluxeMenus/menus/shop.yml`, preview the conversion: ``` /cmdp migrate --dry-run DeluxeMenus/menus/shop.yml ``` The preview reports the number of changed prompts and shows up to 20 before/after examples with line numbers. It does not write files or create a backup. Apply the conversion with: ``` /cmdp migrate DeluxeMenus/menus/shop.yml ``` The command creates a backup before replacing the file. On success, it reports the number of converted prompts, the backup location, and the exact undo command for that backup. If there is nothing to migrate, no file write or backup occurs. If any tag needs manual attention, the entire file remains unchanged. Correct the reported lines and preview again. ### Paths and autocomplete Migration paths are relative to the server's `plugins/` directory. Do not include `plugins/` at the beginning of the argument. Press TAB after `/cmdp migrate` to browse plugin folders, then continue completing folders and files at each level. Directories end with `/`. Autocomplete also works after `--dry-run`. Paths containing spaces work with or without surrounding double quotes: ``` /cmdp migrate --dry-run "DeluxeMenus/menus/my shop.yml" ``` Autocomplete returns up to 100 matches from the first 4,096 entries inspected in the selected directory. Normal migration suggestions exclude migration backups, symlinks, hidden files, and recognized binary or temporary files. ## Syntax conversions These examples use the default prompt and answer-reference delimiters: | V2 | V3 | | ------------------------ | ----------------------- | | `<-a Enter a name>` | `` | | `<-s Enter a name>` | `` | | `<-p Select a player>` | `` | | `<-p:w Select a player>` | `` | | `<-exa say p:0>` | `` | | `<-exac say Cancelled>` | `` | | `<-exa:20 say p:0>` | `` | | `<-exa\|c say p:0>` | `` | | `<-exa\|p say p:0>` | `` | Supported flags such as `-ds`, `-iv`, `-int`, and `-str` are retained. Answer references such as `p:0` are converted only inside legacy post-command tags. Built-in player filters `w`, `rN`, and `s`, including supported combinations, can be migrated; unknown filters require manual review. Sign `{br}` lines remain intact. When a label could be interpreted as a V3 filter, the converter inserts an empty filter. For example, `<-s Name:{br}Age:>` becomes ``. This keeps the labels as display text without inserting `:` into an unquoted YAML value. Plain chat prompts whose syntax is unchanged and recognized V3 tags are left intact. Unknown colon-prefixed tags such as `` or `` require manual review because they could be old chat text or custom V3 prompt types. For custom delimiters, the command uses the active [Syntax configuration](/commandprompter/configuration/command-prompter-configuration/syntax.md). Make sure the prompt delimiters match the old file before migrating. Converted answer references use the active template delimiters. ## Backups and undo Backups are stored under: ``` plugins/CommandPrompterPaper/migration-backups// ``` Each backup has a unique directory and contains the original file's exact bytes. Existing backups are retained. To undo a migration, use the command printed with its backup, or press TAB after `/cmdp migrate undo` to find it. The command pattern is: ``` /cmdp migrate undo /DeluxeMenus/menus/shop.yml ``` Replace `` with the actual directory suggested by TAB. **Undo paths are relative to `CommandPrompterPaper/migration-backups/`**, unlike normal migration paths. Nested paths and spaces are supported. Undo restores the selected backup to its original destination. Before doing so, it saves the destination's current contents as another backup, including edits made after migration. It retains both backups and prints a restore command for the newly saved contents, so you can reverse the undo if needed. If the destination already matches the selected backup, undo reports that no changes are needed and creates no additional backup. The destination file must still exist; to recover a deleted file, copy the saved backup to the original location manually. ## Supported files and errors The tool accepts UTF-8 text configurations up to 8 MiB without requiring a particular plugin or configuration schema. It edits prompt spans directly instead of loading and saving the entire configuration through a YAML serializer. Formatting and text outside those spans remain intact. XML-escaped and JSON Unicode-escaped prompt delimiters are also recognized. This migrates embedded prompt syntax, not configuration keys, plugin schemas, or permission assignments. Unknown custom prompts, unsupported escapes, ambiguous syntax, and failed V3 validation are reported for manual attention. The report shows up to 20 issues with line numbers. | Result | What to do | | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Nothing to migrate / already matches backup | No file write or new backup occurred. | | Manual attention required | Review the reported lines, convert unsupported syntax manually, then preview again. The file was not changed. | | File not found | Check the path. For undo, both the backup and destination must exist. | | Invalid path | Use TAB from the appropriate command. Absolute paths, parent traversal, and symlinks are rejected. | | Unsupported file or size limit | Use a UTF-8 text configuration no larger than 8 MiB. Binary, backup, hidden, temporary, and log files are excluded from migration. | | Read or backup failure | Check file permissions and the server log. A backup failure prevents replacement of the original file. | | File changed or operation already running | Wait for other writes or migrations to finish before retrying. | | Replacement failure | Check the server log. The original was not replaced; the completed backup is retained. | Migration and undo share the same per-file concurrency protection and require an atomic file replacement. There is no fallback to a potentially partial overwrite. The tool checks current contents immediately before replacement, but cannot coordinate independent saves made by other plugins. ## Localized messages All migration and undo feedback is available in the ten [bundled locales](/commandprompter/configuration/internationalization-i18n.md). Messages follow the configured `Locale` and can be customized through `locales/messages_.properties` overrides. Migration messages use `command.migrate.*`; undo messages use `command.migrate.undo.*`. For example: ```properties command.migrate.nothing=No old prompts found in %path%. No files changed. command.migrate.undo.nothing=%path% already matches the selected backup. command.migrate.undo.success=Restored %path%. The previous contents were backed up. ``` Keep each message's placeholders, such as `%path%`, `%count%`, `%line%`, `%before%`, and `%after%`. Run `/cmdp reload` after editing locale overrides; this reloads CommandPrompter's messages, not another plugin's migrated configuration. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cyr1en.gitbook.io/commandprompter/features/prompt-migration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.