Immich CLI 指令介面
Immich 提供命令行介面 (CLI)，允許您通過命令行執行某些操作。
功能
- 上傳照片和影片到 Immich
- 檢查伺服器版本
未來還計劃添加更多功能。
如果你想匯入 Google 相簿的 Takeout，推薦使用由社群維護的工具 immich-go
系統要求
- Node.js 20 或以上版本
- Npm
如果你無法安裝 node/npm，也提供 Docker 版本。
安裝 (NPM)
npm i -g @immich/cli
注意：如果您之前安裝過舊版 CLI，請先卸載它：
npm uninstall -g immich
安裝 (Docker)
如果系統上無法使用 npm，可以嘗試 Docker 版本
docker run -it -v "$(pwd)":/import:ro -e IMMICH_INSTANCE_URL=https://your-immich-instance/api -e IMMICH_API_KEY=your-api-key ghcr.io/immich-app/immich-cli:latest
請根據需要修改 IMMICH_INSTANCE_URL 和 IMMICH_API_KEY 環境變數。您也可以使用 Docker env 文件來存儲敏感的 API 密鑰。
此 docker run 命令會直接在容器內執行 immich 指令。您可以直接在命令行後追加所需的參數（見 "使用方法"），例如：
docker run -it -v "$(pwd)":/import:ro -e IMMICH_INSTANCE_URL=https://your-immich-instance/api -e IMMICH_API_KEY=your-api-key ghcr.io/immich-app/immich-cli:latest upload -a -c 5 --recursive directory/
使用方法
使用方法
$ immich
使用方法: immich [options] [command]
Immich 的命令行介面
選項:
-V, --version 輸出版本號
-d, --config-directory <directory> 配置目錄，用於存儲 auth.yml 文件 (默認: "~/.config/immich/", 環境變數: IMMICH_CONFIG_DIR)
-u, --url [url] Immich 伺服器 URL (環境變數: IMMICH_INSTANCE_URL)
-k, --key [key] Immich API 密鑰 (環境變數: IMMICH_API_KEY)
-h, --help 顯示命令幫助
命令:
login|login-key <url> <key> 使用 API 密鑰登錄
logout 移除存儲的憑證
server-info 顯示伺服器信息
upload [options] [paths...] 上傳資源
help [command] 顯示命令幫助
命令
上傳命令支持以下選項：
選項
使用方法: immich upload [paths...] [options]
上傳資源
參數:
paths 一個或多個要上傳的資源路徑
選項:
-r, --recursive 是否遞歸 (默認: false, 環境變數: IMMICH_RECURSIVE)
-i, --ignore <pattern> 忽略的模式 (環境變數: IMMICH_IGNORE_PATHS)
-h, --skip-hash 不在上傳前哈希文件 (默認: false, 環境變數: IMMICH_SKIP_HASH)
-H, --include-hidden 包括隱藏文件夾 (默認: false, 環境變數: IMMICH_INCLUDE_HIDDEN)
-a, --album 根據文件夾名稱自動創建相簿 (默認: false, 環境變數: IMMICH_AUTO_CREATE_ALBUM)
-A, --album-name <name> 將所有資源添加到指定相簿 (環境變數: IMMICH_ALBUM_NAME)
-n, --dry-run 不執行任何操作，只顯示將完成的內容 (默認: false, 環境變數: IMMICH_DRY_RUN)
-c, --concurrency <number> 同時上傳的資源數量 (默認: 4, 環境變數: IMMICH_UPLOAD_CONCURRENCY)
-j, --json-output 輸出詳細信息為 JSON 格式 (默認: false, 環境變數: IMMICH_JSON_OUTPUT)
--delete 上傳後刪除本地資源 (環境變數: IMMICH_DELETE_ASSETS)
--no-progress 隱藏進度條 (環境變數: IMMICH_PROGRESS_BAR)
--watch 監視更改並自動上傳 (默認: false, 環境變數: IMMICH_WATCH_CHANGES)
--help 顯示命令幫助
注意以上選項也可以通過環境變數設定。
快速開始
您可以通過向 Immich 伺服器進行身份驗證來開始。例如：
# immich login [url] [key]
immich login http://192.168.1.216:2283/api HFEJ38DNSDUEG
這會將您的憑證存儲在默認配置目錄中的 auth.yml 文件中，默認路徑為 ~/.config/immich/。可以使用 -d 選項或環境變數 IMMICH_CONFIG_DIR 設定目錄。請確保文件安全，完成操作後可以使用 logout 命令或手動刪除文件。
完成身份驗證後，您可以上傳資源到 Immich 伺服器。
immich upload file1.jpg file2.jpg
默認情況下不包含子文件夾。若需包含子文件夾，可使用 --recursive 選項：
immich upload --recursive directory/
如果您不確定會發生什麼，可以使用 --dry-run 選項查看會執行的操作而不真的執行。
immich upload --dry-run --recursive directory/
默認情況下，上傳命令會在上傳文件之前對其進行哈希處理，以避免重複上傳相同文件。如果您確定文件是唯一的，可以使用 --skip-hash 選項跳過這一步。請注意 Immich 始終通過哈希執行自己的去重操作，因此這僅僅是一個性能考慮。如果您的網路速度良好，跳過哈希可能更快。
immich upload --skip-hash --recursive directory/
您可以通過 --album 選項根據文件夾名稱自動創建相簿。這將根據資源所在的文件夾名稱自動為每個上傳資源創建相簿。
immich upload --album --recursive directory/
您還可以使用 --album-name 選項選擇將所有資源上傳至指定相簿。
immich upload --album-name "我的暑假" --recursive directory/
可以通過 --ignore 選項跳過匹配 glob 樣式的資源。請參見 庫文檔 瞭解如何使用 glob 樣式。如果需要，可以添加多個排除樣式。
immich upload --ignore **/Raw/** --recursive directory/
immich upload --ignore **/Raw/** **/*.tif --recursive directory/
默認情況下隱藏文件會被忽略。如果您想包含隱藏文件，請使用 --include-hidden 選項：
immich upload --include-hidden --recursive directory/
您可以使用 --json-output 選項獲得包括三個鍵的 json 輸出：newFiles、duplicates 和 newAssets。由於某些日誌輸出，您需要刪除前面三行內容才能獲得 json。例如，獲取將上傳的文件列表進行進一步處理：
immich upload --dry-run . | tail -n +4 | jq .newFiles[]
獲取 API 密鑰
API 密鑰可以在網頁介面的使用者設定面板中獲得。
