How to Use the Command 'immich-cli' (with examples)
The ‘immich-cli’ is a powerful command-line interface designed to allow users to interact with the Immich server directly from their terminal. With this tool, users can perform a variety of tasks like authenticating to the Immich server, uploading image files, creating albums, and selectively managing their uploads based on patterns, all through simple command-line operations.
Authenticate to Immich Server
Code:
immich login server_url/api server_key
Motivation:
Authenticating to the Immich server is a crucial first step in utilizing any command-line functions. It ensures a secure connection between your local machine and the server, allowing for authenticated requests that maintain integrity and security of your data transactions.
Explanation:
immich: This is the command-line tool you are using.login: This subcommand is responsible for initiating the authentication process.server_url/api: Replace this with the specific URL of your Immich server’s API endpoint.server_key: This is the authentication key or token that verifies your identity and authorization level on the server.
Example Output:
Upon successful execution, you might see an output like:
Authentication successful!
Welcome to Immich CLI, [username]!
Upload Some Image Files
Code:
immich upload file1.jpg file2.jpg
Motivation:
Uploading individual image files is useful when you want to selectively send specific images to the server, perhaps after editing or from different locations on your file system.
Explanation:
immich: Denotes the command-line tool in use.upload: The subcommand to specify the task of uploading files.file1.jpg file2.jpg: These are the specific file names of images you want to upload. Replace with actual file names as needed.
Example Output:
Uploading file1.jpg ... done!
Uploading file2.jpg ... done!
Uploaded 2 files successfully.
Upload a Directory Including Subdirectories
Code:
immich upload --recursive path/to/directory
Motivation:
Uploading an entire directory, including its subdirectories, supports users who work with organized folder structures. It allows batch-uploading of images, which is time-saving when dealing with large numbers of files spread across various folders.
Explanation:
immich: Indicates the use of the Immich CLI tool.upload: Command for uploading files.--recursive: This flag ensures that all subdirectories within the specified directory are included in the upload.path/to/directory: The path to the directory you wish to upload.
Example Output:
Preparing to upload contents from: /path/to/directory
Uploading file1.jpg ... done!
Uploading subfolder/file2.jpg ... done!
All files in directory '/path/to/directory' uploaded successfully.
Create an Album Based on a Directory
Code:
immich upload --album-name "My summer holiday" --recursive path/to/directory
Motivation:
Creating albums from directories is particularly useful for users who prefer their digital image collections to be organized thematically or by events, such as holidays. It automatically structures uploaded photos into an album, facilitating better organization and access on the server.
Explanation:
immich: CLI tool in use.upload: Initiating an upload command.--album-name "My summer holiday": Creates a new album titled “My summer holiday” to which all uploaded images will belong.--recursive: Ensures that all subfolders are included as part of the upload.path/to/directory: Specifies the directory path whose contents will be uploaded and placed in the album.
Example Output:
Creating album: My summer holiday
Uploading file1.jpg ... added to album.
Uploading file2.jpg ... added to album.
Album 'My summer holiday' created with 2 images.
Skip Assets Matching a Glob Pattern
Code:
immich upload --ignore **/Raw/** **/*.tif --recursive path/to/directory
Motivation:
Skipping assets that match specific patterns (using glob syntax) can be particularly beneficial for users who need to exclude certain file types or organizational structures from uploads. This is helpful when the directory contains files that are not ready for upload or irrelevant for a specific use-case, such as raw format images.
Explanation:
immich: The Immich CLI tool.upload: Command indicating upload operation.--ignore **/Raw/** **/*.tif: Specifies patterns to be excluded from the upload. For example, any file in a “Raw” directory or files with the “.tif” extension.--recursive: Ensures all directories and subdirectories are checked for files to upload or ignore.path/to/directory: Base directory path for the operation.
Example Output:
Skipping files in 'Raw' folders.
Skipping .tif files.
Uploading file1.jpg ... done!
Finished upload with 1 file skipped.
Include Hidden Files
Code:
immich upload --include-hidden --recursive path/to/directory
Motivation:
Including hidden files in uploads caters to users who work with images or data that might be marked as hidden, whether intentional due to system preferences or not. This is crucial for comprehensive data backup or transfer of complete directory contents where hidden files are significant.
Explanation:
immich: Refers to the command-line interface being utilized.upload: Indicates the task being executed is an upload.--include-hidden: This flag ensures that files marked as hidden (usually those starting with a.) are also uploaded.--recursive: Allows the operation to traverse into subdirectories.path/to/directory: Path to the target directory for upload.
Example Output:
Scanning /path/to/directory for hidden files...
Uploading .hiddenfile.jpg ... done!
Finished uploading including all hidden files.
Conclusion:
The ‘immich-cli’ is a versatile tool that provides straightforward command-line commands for various upload tasks to an Immich server. Whether you are organizing photos into albums, managing bulk uploads, or sorting specific types of files with precision, ‘immich-cli’ aids in streamlining the process, ensuring efficiency, and improving your workflow.
