Immich CLI

Immich는 커맨드라인 인터페이스(CLI)를 제공하여 명령어를 통해 특정 작업을 수행할 수 있습니다.

기능

• Immich에 사진 및 비디오 업로드
• 서버 버전 확인

다양한 기능이 앞으로 추가될 예정입니다.

구글 사진 Takeout

구글 사진 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 환경 변수 값을 적절히 수정하십시오. 민감한 API 키를 저장하기 위해 Docker env 파일을 사용할 수도 있습니다.

이 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>  구성 디렉토리 (기본값: "~/.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 login [url] [key]
immich login http://192.168.1.216:2283/api HFEJ38DNSDUEG

이는 auth.yml 파일에 인증 정보를 설정 디렉토리에 저장합니다. 기본 설정 경로는 ~/.config/immich/입니다. 디렉토리는 -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 "My summer holiday" --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 옵션을 사용하여 newFiles, duplicates 및 newAssets 키를 포함하는 JSON 출력을 얻을 수 있습니다. 일부 로그 출력 때문에 JSON을 얻으려면 첫 3줄을 제거해야 합니다. 이후 추가 처리를 위해 업로드될 파일 목록을 얻으려면 다음과 같이 사용할 수 있습니다:

immich upload --dry-run . | tail -n +4 | jq .newFiles[]

API 키 가져오기

API 키는 웹 인터페이스의 사용자 설정 패널에서 얻을 수 있습니다.