上一篇文章 工具安裝攻略：帶你完成 cli-kintone 的安裝 安裝好後，這篇就一起來操作 cli-kintone，將各種包含附件的紀錄匯入匯出。
從官網中可以看到以下幾種操作：

• record export：匯出紀錄
• record import：匯入紀錄
• record delete：刪除紀錄
• plugin info：查看外掛詳情（開發階段）
• plugin pack：打包外掛（開發階段）

在撰文當下（2025/02），plugin info 以及 plugin pack 還在早期開發階段，而且這兩個功能是針對開發者的，所以本篇文章會跳過這兩個功能，只針對紀錄操作。

事前準備

開始之前，先來建立練習用的應用程式，我們先在應用程式內新增以下欄位：

• 單行文字方塊
• 附件欄位
• 表格
  • 表格內的單行文字方塊
  • 表格內的附件欄位

為了方便辨識，記得改個欄位名稱，另外也新增幾筆紀錄，在附件欄位內放入一些檔案。

匯出（Export）

首先來看紀錄的匯出，我們在官網找到範例：

cli-kintone record export \
  --base-url https://${yourDomain} \
  --api-token ${apiToken} \
  --app ${kintoneAppId} \
> ${filepath}

我們只要把上面範例的值替換成自己環境的 domain、token、app id 等資訊即可，最後的 ${filepath} 則是輸出後的 csv 檔案，因此經過修改後變成：

cli-kintone record export \
  --base-url https://brown.cybozu.com \
  --api-token pYpEfdnqB1tVI2VhhWQYSN71dBHqunfYpNLn6Cv2 \
  --app 20 \
> test.csv

左邊的 --xxx 就是參數，只要將對應的值放到右邊即可，\ 則是換行符號，當然可以再補上自己需要的參數，例如排序 --order-by、訪客空間 --guest-space-id、輸出欄位 --fields 等等，全部的參數選項，可以參考以下連結：

https://cli.kintone.dev/guide/options/

回到範例。因為我們還要輸出附件，所以再補上新的參數 --attachments-dir，同時指定輸出的資料夾，就會變成：

cli-kintone record export \
  --base-url https://brown.cybozu.com \
  --api-token pYpEfdnqB1tVI2VhhWQYSN71dBHqunfYpNLn6Cv2 \
  --app 20 \
  --attachments-dir ./cli-kintone-files \
> ./cli-kintone-files/test.csv

以上會將輸出的附件及 csv 統一放到名為 cli-kintone-files 的資料夾中。接著我們開啟終端機後直接複製貼上，就會看到輸出後的檔案：

會輸出的這樣的格式，主要是因為附件檔案會建立各自的資料夾，並遵循以下輸出路徑：

• 輸出的資料夾/欄位id-紀錄編號/檔案名稱
• 若有相同附件名稱，則會變成在檔名後方加入數字，例如 dog(2).jpg。

提醒：再次匯出並不會刪除原本的檔案，只有 csv 會被取代成新的，因此如果有重新匯出的需求，建議先將資料夾整個清空，不然就會變成以下情況。

匯入（Import）

跟匯出的指令一樣，只是帶的參數稍有不同。匯入的時候最重要的是 有沒有帶 --update-key，如果有填的話代表這次的匯入是要涵蓋更新，反之則是新增。

為什麼會說是涵蓋？因為如果 --update-key 沒有比對到 csv 的紀錄，則該筆紀錄會以「新增」的方式匯入。

以下是範例：

cli-kintone record import \
  --base-url https://sally.cybozu.com \
  --api-token pYpEfdnqB1t4I4VhhWQYSN71dBHqunSYpNLn23Cb \
  --app 183 \
  --attachments-dir ./ \
  --update-key 記錄號碼 \
  --file-path ./test22.csv

csv 則是：

以上指令指定了 --update-key 為「記錄號碼」，因此會比對 csv 上的檔案將這三筆資料做更新，並且在終端機會看到成功的訊息：

[2025-02-04T10:03:27.881Z] INFO: Preparing to import records...
[2025-02-04T10:03:28.593Z] INFO: Starting to import records...
[2025-02-04T10:03:30.438Z] INFO: Imported 3 records successfully

如果新增了一筆沒有比對到 --update-key 的資料，則該筆資料會以「新增」的方式匯入到 kintone。

一樣會成功：

[2025-02-05T05:50:00.868Z] INFO: Preparing to import records...
[2025-02-05T05:50:01.446Z] INFO: Starting to import records...
[2025-02-05T05:50:03.127Z] INFO: Imported 4 records successfully

注意事項：--update-key 只能指定為 紀錄編號、或是唯一值的單行文字方塊/數字欄位。

再來我們試試看用新增的方式匯入，將指令的 --update-key 刪除，重新輸入後，會得到一個錯誤：

[2025-02-05T06:01:52.365Z] INFO: Starting to import records...
[2025-02-05T06:01:53.939Z] INFO: Imported 0 of 4 records successfully
[2025-02-05T06:01:53.940Z] ERROR: Failed to add all records.
[2025-02-05T06:01:53.940Z] ERROR: No records are processed successfully.
[2025-02-05T06:01:53.940Z] ERROR: An error occurred while processing records.
[2025-02-05T06:01:53.940Z] ERROR: [400] [GAIA_UN10] Cannot update field whose type is RECORD_ID. (QSvju4wp6ewE4lE2xLYa)

原因是「紀錄編號」是 RECORD_ID，我們還沒將 csv 的紀錄編號欄位刪除，所以發生了錯誤，只要把該欄從 csv 刪除就可以匯入成功了。

附件的更新

其實上面的指令就有偷渡匯入附件了，就是 --attachments-dir 參數，這個代表的附件的目錄位置，如果終端機目前在 Desktop，要上傳的附件目錄在 images 資料夾，就要寫成：

// 目前位置在 Desktop

cli-kintone record import \
  --attachments-dir ./images/ \
  下略...

之後在 csv 中附件欄位寫上檔名就可以，其實只要自己把路徑填好就可以。

多個檔案匯入

如果一個附件欄位有多個檔案要上傳，直接在 csv 中將檔案換行寫上就可以，如下：

刪除（Delete）

刪除最簡單，直接看範例：

cli-kintone record delete \
  --base-url https://${yourDomain} \
  --api-token ${apiToken} \
  --app ${kintoneAppId} \
  --file-path ${filepath}

--file-path 會是最重要的參數，若該參數沒帶，代表這個 app 的全部資料都被刪除，因為沒被指定。

--file-path 必須是一個 csv 檔案，內容包含要刪除的紀錄編號，例如以下，只會刪除編號是 25 的紀錄：

並且在終端機會再次詢問是否刪除：

? Are you sure want to delete records? yes
[2025-02-07T02:11:32.905Z] INFO: Starting to delete records...
[2025-02-07T02:11:33.775Z] INFO: 1 records are deleted successfully

如果不希望他詢問你，可以帶上參數 --yes 變成 force delete：

cli-kintone record delete \
  --base-url https://${yourDomain} \
  --api-token ${apiToken} \
  --app ${kintoneAppId} \
  --yes \
  --file-path ${filepath}

以上就是 cli-kintnoe 的操作方式，希望大家可以活用該工具！