要求

在使用 Immich CLI 之前，请确保您的环境满足以下条件：

• Node.js 20 或更高版本
• npm（Node.js 包管理器）

安装 Immich CLI

全局安装

使用 npm 进行全局安装 Immich CLI：

npm i -g @immich/cli

卸载旧版本

如果您之前安装过旧版 CLI，建议先卸载以避免冲突：

npm uninstall -g immich

快速入门

在使用 Immich CLI 之前，您需要先进行身份验证，并连接到您的 Immich 服务器。

1. 认证登录

您需要使用 API 密钥向 Immich 服务器进行身份验证。
执行以下命令，将 [服务器地址] 和 [API 密钥] 替换为实际值：

immich login [服务器地址] [API 密钥]

示例：

immich login http://192.168.1.216:2283/api HFEJ38DNSDUEG

认证成功后：

• CLI 会自动将您的凭据存储在 auth.yml 配置文件中。
• 默认情况下，该文件位于 ~/.config/ 目录下。
• 如果需要自定义存储目录，可以使用 -d 选项或 IMMICH_CONFIG_DIR 环境变量。

安全提示：

• 为确保账户安全，在使用完 CLI 后，建议执行 immich logout 注销，或手动删除 auth.yml 文件。

2. 上传文件到 Immich 服务器

上传单个或多个文件

如果要上传单个文件或多个文件，可以直接指定文件路径：

immich upload file1.jpg file2.jpg

上传整个目录（默认不包含子文件夹）

如果要上传目录中的所有文件（不包括子目录），可执行：

immich upload directory/

上传包含子文件夹的目录

如果目录中包含多个子文件夹，并希望上传所有内容，请使用 --recursive 选项：

immich upload --recursive directory/

3. 预览上传内容

如果不确定哪些文件会被上传，或者希望在执行前进行确认，可以使用 --dry-run 选项进行模拟运行：

immich upload --dry-run --recursive directory/

此命令不会实际上传文件，只会显示哪些文件将被上传。

4. 提高上传性能

跳过哈希计算

默认情况下，Immich 在上传文件前会计算哈希值，以避免重复上传。
如果您确定文件是唯一的，并希望加快上传速度，可以使用 --skip-hash 选项跳过哈希计算：

immich upload --skip-hash --recursive directory/

注意：

• Immich 服务器仍会进行哈希处理以执行重复数据删除，因此这个选项仅影响客户端性能。
• 如果您的带宽充足，跳过哈希计算可以加快上传速度。

5. 自动管理相册

Immich CLI 支持自动创建相册，并根据文件夹名称或自定义名称进行管理。

根据文件夹名称自动创建相册

使用 --album 选项，Immich 会根据文件夹名称自动创建相册，并将对应文件上传到相册中：

immich upload --album --recursive directory/

上传文件到指定相册

如果希望将所有文件上传到一个特定相册，可以使用 --album-name 选项：

immich upload --album-name "My Summer Holiday" --recursive directory/

6. 过滤上传文件

有时，您可能需要跳过某些文件或目录，Immich 提供了 --ignore 选项来实现文件过滤。

跳过特定文件或文件夹

例如，如果您想跳过 Raw 文件夹下的所有内容，可以执行：

immich upload --ignore **/Raw/** --recursive directory/

排除多个文件类型

可以使用多个 --ignore 规则，匹配不同的文件类型，例如排除 .tif 文件：

immich upload --ignore **/Raw/** **/*.tif --recursive directory/

7. 包含隐藏文件

默认情况下，Immich 不会上传隐藏文件（文件名以 . 开头）。
如果希望上传隐藏文件，可以使用 --include-hidden 选项：

immich upload --include-hidden --recursive directory/

获取 API 密钥

使用 Immich CLI 之前，您需要一个 API 密钥，该密钥可以在 Web 界面的 用户设置面板 中获取。

获取 API 密钥的步骤：

1. 进入 Immich Web 管理界面
2. 在 用户设置 页面中找到 API Key 选项
3. 生成新的 API 密钥并复制，用于 CLI 登录