create-promptex-py

Start a promptex Python project, plugin or adapter from the starter templates bundled with this package, or add promptex to a project you already have.

uvx create-promptex-py my-prompts   # new project in ./my-prompts
uvx create-promptex-py .            # add promptex to the current directory

uvx runs the latest release without installing it first.

After that, declare and install the SDK, then build:

uv add promptex-py
uv run promptex build --install

建立模式與初始化模式

create 依目標目錄自動選模式，輸出的第一行說明選了哪一種：

• 目標不存在，或第一層只有下表的項目時，走建立模式，開一個新專案。
• 其他情況走初始化模式，在原資料夾加入 promptex。初始化模式只支援 project 範本， plugin 與 adapter 遇到這種資料夾會以結束碼 2 拒絕。

兩種模式寫入時都逐檔判斷，既有檔一律不覆寫：

目標本身是符號連結或檔案時，以結束碼 2 拒絕。目標裡的符號連結不跟隨，連到外部的 檔案不會被寫到。

旗標

每個問題都有對應的旗標，可以不互動執行：

uvx create-promptex-py my-prompts --template project --name my-prompts --no-git --yes

沒有終端機、帶 --yes，或環境變數 CI 為真時不提問，全部取預設值。

機器可讀的試跑結果

--dry-run --json 在 stdout 輸出一行 JSON，欄位與另兩個 create 套件 （create-promptex-js、create-promptex-rs）相同，只有 package 與 language 不同：

{"formatVersion":"1.2","package":{"name":"create-promptex-py","version":"1.0.1"},"language":"python",
 "mode":"init","alreadyInitialized":false,"existingConfig":null,"target":"/work/app",
 "template":"project","name":"app",
 "files":{"create":["promptex.config.py","prompts/example.py","prompts/example_skill.py"],
          "overwrite":[],"append":[".gitignore"],
          "skip":[{"path":"README.md","reason":"init-mode"},{"path":"pyproject.toml","reason":"manifest-kept"}]},
 "git":{"init":false,"reason":"inside-worktree"}}

失敗時 stdout 是一份錯誤 JSON，stderr 另寫一行同文的訊息：

{"formatVersion":"1.2","error":{"code":"USAGE_TEMPLATE_NEEDS_EMPTY_DIR","message":"…","details":{"template":"plugin","path":"/work/app","entries":["src"]}}}

結束碼是 0 成功（含已初始化）、1 執行失敗、2 用法錯誤。程式只比對 error.code： USAGE_ 開頭是呼叫本身不對，RUN_ 開頭是執行失敗。

語系與模板

語系未以 --locale 指定時，依序讀 PROMPTEX_LOCALE、LANGUAGE、LC_ALL、 LC_MESSAGES、LANG，都沒有就用英文；LC_ALL=C 意為關掉在地化。zh-TW、 zh-HK、zh-MO 與 zh-Hant-* 都對到 zh-Hant。它同時決定鋪出來的範例資源 用哪個語系寫（ADR-030）：那份內容從產出 當下起就歸你，框架不再改寫它。plugin 與 adapter 骨架裡教你怎麼填的註解維持英文。

模板隨本套件一起發布，鷹架時不需要網路，每個版本具現化的都是它發布時的模板。 {{promptexVersion}} 於鷹架當下以本套件版本填入，三套件與 SDK 同版發布。

promptex init 已棄用，2.0 移除。它能做的事改由本工具的初始化模式處理。