跳转到主要内容

Immich CLI

Immich拥有一个命令行界面(CLI)，允许您从命令行执行某些操作。

功能​

  • 将照片和视频上传到Immich
  • 检查服务器版本

未来将计划提供更多功能。

::: 提示 Google 照片导出 如果您正在寻找导入Google照片导出的方法，我们推荐这个社区维护的工具 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环境文件来存储敏感的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]                      为命令显示帮助信息

命令​

upload命令支持以下选项：

选项
使用方法: 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 登录 [url] [密钥]
immich login http://192.168.1.216:2283/api HFEJ38DNSDUEG

这将把您的凭据存储在默认配置目录中~/.config/immich/的auth.yml文件中。您可以使用-d选项或环境变量IMMICH_CONFIG_DIR设置该目录。请确保将此文件保管安全，可以在使用后执行注销命令或手动删除。

一旦您验证通过后，就可以将资源上传到您的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选项，跳过与通配模式匹配的资源。请参阅库文档了解如何使用通配模式。如果需要，您可以添加多个排除模式。

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密钥​

您可以在Web界面用户设置面板中获取API密钥。

获取API密钥