過去，kintone 的外掛與客製化開發需要搭配多個分散的 npm 套件：

• @kintone/create-plugin：建立外掛範本
• @kintone/plugin-packer：將外掛打包為 zip 檔案
• @kintone/plugin-uploader：上傳外掛至 kintone
• @kintone/customize-uploader：上傳／下載 kintone 應用程式客製化設定

這些工具各自獨立、選項命名不一致，光是熟悉每個工具的用法就要花費不少時間。

Cybozu 於 2026 年 2 月 8 日 正式將上述功能全數整合進 cli-kintone，讓從開發到部署的整個流程都能在單一工具內完成，大幅降低學習門檻。

與此同時，原有的四個獨立工具預計於 2026 年 8 月 結束維護，屆時可能無法正常運作，請務必在此之前完成遷移。

介面與操作行為的改善

cli-kintone 根據 kintone/js-sdk 的使用回饋進行了多項改善：

• 明確的私鑰產生流程：私鑰產生獨立為專屬的 plugin keygen 指令，讓金鑰產生的行為更加明確清楚
• 一致的選項設計：所有指令統一使用相同的選項名稱（如 --input、--output），操作更加直覺
• 新增功能：透過 plugin info 指令可以查看外掛的詳細資訊

此外，部分指令在內部行為上也有所改善：

• plugin upload：改用 kintone REST API 進行上傳，相較於舊版 plugin-uploader 依賴 RPA 的方式，穩定性與速度均有提升

工具對照表

主要差異

指令結構

• js-sdk： 每個工具為獨立的 npm 套件，擁有各自的指令
• cli-kintone： 所有開發指令統一整合至 cli-kintone plugin 與 cli-kintone customize 命名空間下

選項名稱

部分選項名稱在兩者之間有所不同：

詳細的介面差異請參閱 各指令的介面與行為差異。

遷移步驟

Step 1：安裝 cli-kintone

將 cli-kintone 安裝至全域環境或是專案內。詳細說明請參閱官方文件中的 安裝指南。

npm install @kintone/cli --global

Step 2：更新指令用法

▍建立新外掛

遷移前（js-sdk）：

kintone-create-plugin my-plugin

遷移後（cli-kintone）：

cli-kintone plugin init --name my-plugin

▍產生私鑰

使用 js-sdk 的 create-plugin 時，私鑰會在第一次打包時自動產生；
使用 cli-kintone 則是在執行 plugin init 時產生。
若需要重新產生，請執行以下指令：

cli-kintone plugin keygen --output private.ppk

▍打包外掛

遷移前（js-sdk）：

kintone-plugin-packer --ppk private.ppk --out plugin.zip ./src/

遷移後（cli-kintone）：

cli-kintone plugin pack --input ./src/manifest.json --output ./plugin.zip --private-key ./private.ppk

監看模式（Watch mode）：

cli-kintone plugin pack --input ./src/manifest.json --output ./plugin.zip --private-key ./private.ppk --watch

▍上傳外掛

遷移前（js-sdk）：

kintone-plugin-uploader --base-url https://example.cybozu.com --username admin --password password plugin.zip

遷移後（cli-kintone）：

cli-kintone plugin upload --input ./plugin.zip --base-url https://example.cybozu.com --username admin --password password

監看模式（Watch mode）：

cli-kintone plugin upload --input ./plugin.zip --base-url https://example.cybozu.com --username admin --password password --watch

▍查看外掛資訊

cli-kintone 新增了查看外掛基本資訊的指令，可顯示 ID、版本與名稱等內容：

cli-kintone plugin info --input ./plugin.zip --format json
# {
#   "id": "pgcfbflalhmhegedmocldhknhpmfmpji",
#   "name": "kintone-plugin",
#   "version": 1,
#   "description": "kintone-plugin",
#   "homepage": null
# }

▍初始化客製化 Manifest 檔案

遷移前（js-sdk）：

kintone-customize-uploader init

遷移後（cli-kintone）：

cli-kintone customize init

▍從 kintone 產生 Manifest 檔案

遷移前（js-sdk）：

kintone-customize-uploader import customize-manifest.json --base-url https://example.cybozu.com --username admin --password password

遷移後（cli-kintone）：

cli-kintone customize export --app 123 --output customize-manifest.json --base-url https://example.cybozu.com --username admin --password password

▍套用客製化設定

遷移前（js-sdk）：

kintone-customize-uploader customize-manifest.json --base-url https://example.cybozu.com --username admin --password password

遷移後（cli-kintone）：

cli-kintone customize apply --input customize-manifest.json --app 123 --base-url https://example.cybozu.com --username admin --password password

3. 更新 package.json 腳本

若 npm scripts 中有使用 js-sdk 工具，請一併更新為 cli-kintone：

遷移前（js-sdk）：

{
  "scripts": {
    "start": "kintone-plugin-packer --ppk private.ppk --watch src/",
    "build": "kintone-plugin-packer --ppk private.ppk src/",
    "upload": "kintone-plugin-uploader --base-url https://example.cybozu.com --username admin --password password plugin.zip"
  }
}

遷移後（cli-kintone）：

{
  "scripts": {
    "start": "cli-kintone plugin pack --input ./src/manifest.json --private-key ./private.ppk --watch",
    "build": "cli-kintone plugin pack --input ./src/manifest.json --private-key ./private.ppk",
    "upload": "cli-kintone plugin upload --input ./plugin.zip --base-url https://example.cybozu.com --username admin --password password"
  }
}

4. 移除 js-sdk 工具（選擇性）

完成遷移後，可視需要移除 js-sdk 相關套件：

npm uninstall @kintone/create-plugin @kintone/plugin-packer @kintone/plugin-uploader

各指令的介面與行為差異

plugin init（對應 @kintone/create-plugin）

範例：

# js-sdk
kintone-create-plugin my-plugin --template minimum

# cli-kintone
cli-kintone plugin init --name my-plugin --template javascript

plugin pack（對應 @kintone/plugin-packer）

範例：

# js-sdk
kintone-plugin-packer --ppk private.ppk --out plugin.zip src/

# cli-kintone
cli-kintone plugin pack --input ./src/manifest.json --output ./plugin.zip --private-key ./private.ppk

plugin upload（對應 @kintone/plugin-uploader）

範例：

# js-sdk
kintone-plugin-uploader --base-url https://example.cybozu.com --username admin --password password plugin.zip

# cli-kintone
cli-kintone plugin upload --input ./plugin.zip --base-url https://example.cybozu.com --username admin --password password

customize init（對應 @kintone/customize-uploader）

範例：

# js-sdk
kintone-customize-uploader init

# cli-kintone
cli-kintone customize init

customize export（對應 @kintone/customize-uploader）

cli-kintone 的 customize export 指令對應 customize-uploader 的 import 子指令。

舊指令的概念為「將 kintone 應用程式的客製化設定匯入到本地 manifast 檔案中」，整合至 cli-kintone 後的概念為「從 kintone 應用程式客製化設定匯出為 manifast 檔」，語意上更直觀，指令也更明確。

範例：

# js-sdk
kintone-customize-uploader import customize-manifest.json --base-url https://example.cybozu.com --username admin --password password

# cli-kintone
cli-kintone customize export --app 123 --output customize-manifest.json --base-url https://example.cybozu.com --username admin --password password

customize apply（對應 @kintone/customize-uploader）

範例：

# js-sdk
kintone-customize-uploader customize-manifest.json --base-url https://example.cybozu.com --username admin --password password

# cli-kintone
cli-kintone customize apply --input customize-manifest.json --app 123 --base-url https://example.cybozu.com --username admin --password password

Manifest 檔案規格

cli-kintone 的 manifest 檔案與 customize-uploader 採用相同格式。

{
  "scope": "ALL",
  "desktop": {
    "js": [
      "https://js.cybozu.com/jquery/3.3.1/jquery.min.js",
      "sample/customize.js"
    ],
    "css": ["sample/51-modern-default.css"]
  },
  "mobile": {
    "js": ["https://js.cybozu.com/jquery/3.3.1/jquery.min.js"],
    "css": []
  }
}

為維持與 customize-uploader 的相容性，manifest 檔案中的 app 屬性雖然會被接受，但實際上會被忽略。cli-kintone 以 --app 選項所指定的應用程式 ID 為準。

時程提醒

• 2026/02/08：cli-kintone 新增的 plugin / customize 指令正式開放
• 2026/08（預定）：create-plugin、plugin-packer、plugin-uploader、customize-uploader 四個舊工具結束維護

距離舊工具停止維護還有幾個月的時間，但遷移涉及指令結構與選項的調整，若有在 CI/CD pipeline 或多個專案中使用這些工具，建議盡早排入規劃，逐一更新。

遇到問題可以參考 cli-kintone 官方文件 或前往 GitHub Issues 回報。