idrive v0.0.2
Unofficial iCloud Drive client for Linux built on the icloud.com/drive API
Overview
This is a client for iCloud Drive built on top of a non-public API. It aims to minimize API requests by utilizing caching. Developed with fp-ts, io-ts, yargs-command-wrapper for args parsing.
Disclaimer
This is an unofficial client. Use it at your own risk. The author is not responsible for any data loss or any other issues that may arise from using this software. Always have a backup of your data.
Installation
npm install -g idrive
Usage
- Fish shell completions for
idrive
are available
idrive init Init new session
idrive auth Authenticate a session
idrive ls [paths..] List files in a folder
idrive mkdir <path> Create a folder
idrive cat <path> View the content of a text file
idrive edit <path> Edit a text file
idrive mv <srcpath> <dstpath> Move or rename a file or a folder
idrive rm [paths..] Remove files and folders
idrive download <paths..> Download a file or a folder
idrive upload <paths..> Upload files and folders
idrive recover <path> Recover a file from the trash
idrive autocomplete <path> Autocomplete path
Options:
--help Show help [boolean]
--version Show version number [boolean]
--session-file Session file
--cache-file Cache file
--no-cache Disable cache [boolean] [default: false]
-a, --api-usage API usage strategy
[string] [choices: "onlycache", "fallback", "validate", "o", "f", "v"]
[default: "validate"]
-d, --debug [boolean] [default: false]
init
Initializes new session.
idrive init
idrive init --session-file myicloud.json
Do not login, just create the session file.
idrive init --skip-login
Authenticate the session file
idrive auth
idrive auth --session-file myicloud.json
Use ICLOUD_SESSION_FILE
environment variable to specify the session file
export ICLOUD_SESSION_FILE=~/.config/idrive/icloud-session.json
ls
List directory contents. Supports globs
idrive ls
idrive ls /MyNotes/my1/
idrive ls '/MyNotes/my1/*.md'
idrive ls -l '/Camera/*.{png,PNG,jpg}'
Multiple paths
idrive ls /MyNotes/ '/Camera/*.jpg' /Pages/Report.pages
More verbose output (adds size, date, item type)
idrive ls -l /MyNotes/my1/
More verbose output (adds drivewsid, etag)
idrive ls -ll /MyNotes/my1/
Print folder or file info
idrive ls -i /MyNotes/my1/ '/Camera/IMG_0198.jpg'
Print full paths
idrive ls -f /MyNotes/my1/
Human readable sizes
idrive ls -lh /MyNotes/my1/
Sorting
idrive ls -S size /
idrive ls -S date /
Recursive listing (may take some time to process deep trees). Note: the command below will save the whole tree into the cache
idrive ls -R /
idrive ls -R / /MyNotes
Use recursive flag for the globstar pattern
idrive ls -R '/MyNotes/my1/**/*.md'
Limit the depth of recursion
idrive ls -R -D 2 '/MyNotes/my1/**/*.md'
Sort by size recursively looking for the largest files
idrive ls -S size -R -h /
Output result as a tree
idrive ls -R -D 2 --tree /MyNotes/my1/
idrive ls -R -T '/MyNotes/my1/**/*.md'
Search in the cache (will fail if the cache is not enough to fulfill the request)
idrive ls -R '/**/*.md' -a onlycache
Search in the cache and fall back to the API if the cache is not enough
idrive ls -R '/**/*.md' -a fallback
Print cached tree
idrive ls -RT -a o /
Same for trash
idrive ls --trash ...
rm paths..
Removes files and folders. Supports globs. By default moves files to the trash
idrive rm '/MyNotes/my1/note.md'
Multiple paths
idrive rm '/MyNotes/my1/*.md' /Camera/IMG_0198.jpg
Use recursion flag for the globstar pattern
idrive rm -R '/MyNotes/my1/**/*.md'
Use --dry
flag to check what is going to be removed
idrive rm -R '/MyNotes/my1/**/*.md' --dry
Delete file skipping trash
idrive rm --skip-trash /Camera/IMG_0198.jpg
Do not ask for the confirmation
idrive rm --force /Camera/IMG_0198.jpg
Remove from trash (forever)
idrive rm --trash /file.txt
cat
View the content of a text file
idrive cat /MyNotes/my1/note.md
mv
Move or rename a file or a folder. You cannot move between different zones (e.g. between APP_LIBRARIES and Docws)
Remote file will be renamed
idrive mv /MyNotes/my1/note1.md /MyNotes/my1/note2.md
Remote file will be moved and renamed
idrive mv /MyNotes/my1/note1.md /MyNotes/old/note2.md
Remote file will be moved
idrive mv /MyNotes/my1/note1.md /MyNotes/note1.md
recover
Recover a file from the trash
idrive recover '/note1.md'
mkdir
Creates a folder
idrive mkdir /MyNotes/my1/notes/
edit
Editing works by downloading the file to a temporary file and uploading it back. It seems there is no way to overwrite remote file, so the remote file will be removed before uploading.
Opens the file in vi
. If the file is not found, it will be created.
idrive edit /MyNotes/my1/notes/note1.md
Opens the file in a different editor (defaults to vi
)
idrive edit --editor subl /MyNotes/my1/notes/note1.md
idrive edit /Camera/IMG_0205.PNG --editor gimp
download
Download a file or a folder content.
A single file
idrive download /MyNotes/my1/note1.md outputdir/
idrive download /MyNotes/my1/note1.md outputdir/different_name.md
Multiple files
idrive download /MyNotes/my1/note1.md /MyNotes/my1/note2.md /Camera/IMG_0198.jpg outputdir/
Files from a folder
idrive download /MyNotes/my1/ outputdir/
idrive download /MyNotes/my1/\*.md outputdir/
idrive download '/Camera/*.{png,PNG,jpg}' outputdir/
Do not update atime and mtime of the files (by default they are updated to what remote files have)
idrive download -T /MyNotes/my1/note1.md outputdir/
Skip downloading files with the same size and date
idrive download -S /MyNotes/my1/note1.md outputdir/
Overwrite existing local files without asking
idrive download -o /MyNotes/my1/note1.md outputdir/
Skip downloading existing local files without asking
idrive download -s /MyNotes/my1/note1.md outputdir/
Do not ask for the last confirmation
idrive download -N /MyNotes/my1/note1.md outputdir/
Verbose output
idrive download -v /MyNotes/my1/note1.md outputdir/
Dry run
idrive download --dry /MyNotes/my1/note1.md outputdir/
Recursively download folders.
idrive download -R /MyNotes/my1/ outputdir/
This will download into outputdir/MyNotes/my1/
idrive download -RF /MyNotes/my1/ outputdir/
Limit the depth of recursion
idrive download -R -D 2 /MyNotes/my1/ outputdir/
Globstar pattern is supported
idrive download -R '/MyNotes/my1/diary/**/*.md' outputdir/
include
and exclude
flags can be used to filter files (supports globs)
idrive download -R '/MyNotes/my1/diary/**/*.md' outputdir/
Same as:
idrive download -R '/MyNotes/my1/diary' outputdir/ --include '**/*.md'
Using exclude flag:
idrive download -R '/MyNotes/my1/diary/**/*.md' outputdir/ --include '**/*.png' --exclude '**/Archive/**/*'
The filter is: path is matching the include glob (if not empty) and not matching exclude glob (if not empty)
Use dry
flag to only check what is going to be downloaded.
idrive download -R '/MyNotes/ --dry
upload
Web version of icloud drive doesn't support overwriting files. Old file has to be removed before uploading.
Upload a single file
idrive upload ~/Documents/note1.md /MyNotes/my1/notes/
idrive upload ~/Documents/note1.md /MyNotes/my1/notes/different_name.md
Overwrite existing file (removes the old file before uploading)
idrive upload --overwrite ~/Documents/note1.md /MyNotes/my1/notes/
Upload multiple files
idrive upload ~/Documents/note1.md ~/Documents/note2.md ~/Documents/note3.md /MyNotes/my1/notes/
Upload a folder. Uploading a folder will always create a new folder in the destination folder. Uploading over an existing folder is not allowed currently.
idrive upload -R ~/Documents/ /MyNotes/my1/notes/
Upload a selection of files
idrive upload -R '~/Documents/**/*.md' /MyNotes/my1/notes/
Use dry
flag to only check what is going to be uploaded.
autocomplete
Autocomplete path. Used for shell autocompletions.
Select files
idrive autocomplete --file /
Select folders
idrive autocomplete --dir /
From trash
idrive autocomplete --trash /
Use cache (faster but not always up to date)
idrive autocomplete -a onlycache /
API/cache usage strategy
--api-usage validate
Default behaviour. Always validates cached paths by retrieving them from API.
--api-usage onlycache
Will not use the API. Only retrieve from cache.
--api-usage fallback
Retrieves from API if the cache is not enough.
Short variants: -a o
, -a f
, -a v
Known issues
- state/session is not saved if an error is thrown in SRTE chain
TODO
Need a feature or have an idea? Open an issue!