Working with iOS devices and backups on the command line
iPhone Backup Extractor includes a command-line tool named rictl for working with iOS backups and devices. rictl runs on any platform that iPhone Backup Extractor runs on, and works like any UNIX-style command line tool in terms of argument and help syntax, and shell returns.
Features at a glance:
- UNIX-compatible format (
$?shell return codes, locale-formatted dates, awk-friendly output,stdoutstreams of exported data) - Support for multiple simultaneous search paths
- Support for all formats of encrypted backup
- Support for relative and home-based (
~) paths
rictl shown in macOS Terminal
rictl shown in Windows Command Prompt
Quickstart: extract database files from an iOS backup
Find backups that are available on the local system:
$ rictl backup search
00000000-0000000000000000 02/07/2019 11:33:41 12.3.1 iPhone11,6 ok
Extract all database files from the backup (note the regular expression format):
$ rictl backup extract -u 00000000-0000000000000000 -r "\.db" Extracting HomeDomain/Library/Voicemail/voicemail.db Extracting HomeDomain/Library/Safari/Bookmarks.db Extracting RootDomain/Library/Caches/locationd/consolidated.db Extracting WirelessDomain/Library/CallHistory/call_history.db ...
Command glossary
Getting help
You can get help using rictl as you'd expect, with the rictl help command:
$ rictl help Usage: rictl <command> [args] Available commands: backup Work with a local backup device Work with devices over USB and Wi-Fi Use 'rictl help <command>' for detailed help on a particular command
rictl exposes a backup mode for working with local backups, and a device mode for working with iOS devices over USB or Wi-Fi.
Working with local backups
$ rictl help backup Usage: rictl backup <command> [args] Work with local backups Available commands: search Search for local backups info Show info about a backup list List files in a backup extract Extract files from a backup export Export data from a backup Use 'rictl help backup <command>' for detailed help on a particular backup command
When working with backups, there are five options: search, info, list, extract and export.
Using search to search for local iOS backups
$ rictl help backup search Usage: rictl backup search [args] Search for local backups Available arguments: -s, --search-path=VALUE path to search for backups (two directories deep) -l include full path in listing output -h, --help show this message and exit
At it's simplest, search will show you the backups on your system:
$ rictl backup search
00000000-0000000000000000 02/07/2019 11:33:41 12.3.1 iPhone11,6 ok
The fields shown are whitespace separated, and are:
UDID- Backup creation time
- iOS device version
- iOS device identifier
- Backup status:
okorin-progress
Option -l shows backup paths
You can use -l to include an additional output field with the backup's path:
$ rictl backup search -l
00000000-0000000000000000 02/07/2019 11:33:41 12.3.1 iPhone11,6 ok /Users/afit/Library/Application Support/MobileSync/Backup/00000000-0000000000000000
Option -s searches additional paths
You can use -s to include additional search paths when looking for backups.
$ rictl backup search -s /Users/afit/Google\ Drive\ File\ Stream/My\ Drive/My\ backups/ -s Downloads/ 00000000-0000000000000000 02/07/2019 11:33:41 12.3.1 iPhone11,6 ok DB72CB76A00CB81675F19907D4AC2B298628D83C 09/06/2014 13:57:08 7.1.1 iPhone6,2 ok DB72CB76A00CB81675F19907D4AC2B298628D83C 23/07/2014 12:37:55 8.0 iPhone6,2 ok DB72CB76A00CB81675F19907D4AC2B298628D83C 28/07/2014 12:43:56 8.0 iPhone6,2 ok CDBF062964613D325EB9E41AD83E85EA16B7E399 10/02/2014 14:29:59 7.0.4 iPad4,1 ok 57BE3B9E8087809F53666B887B9DD81B06299078 29/07/2014 14:18:54 7.1 iPhone3,1 ok F60040E968F533434B9B6CCA10C7E0C673B7CC13 07/10/2014 09:44:17 8.0.2 iPhone7,2 ok CC5D2A27218BD9E4A14B1E59918171A8676EF5BB 26/03/2015 11:07:42 2.2.1 iPhone1,1 ok 46A663D1A1A5C5146476A2C6164EA5F5FE771294 26/03/2015 11:09:54 4.2.1 iPhone1,2 ok 9F8FDEEFFCDA4BD53CA4D6F8229A04497CA5FA4C 31/10/2016 17:05:36 10.1.1 iPhone9,4 ok
- As you'd expect, you can quote (
"My folder") or escape (My\ folder) spaces in paths -scan be used to specify a backup folder or a folder containing backups
Using info to get info and metadata from local iOS backups
$ rictl help backup info Usage: rictl backup info [args] Show info about a backup Available arguments: -u, --udid=VALUE backup UDID -s, --search-path=VALUE path to search for backups (two directories deep) -h, --help show this message and exit
Let's try that out:
$ rictl backup info -u 00000000-0000000000000000 UDID: 00000000-0000000000000000 Path: /Users/afit/Library/Application Support/MobileSync/Backup/00000000-0000000000000000 Backup in progress: False Device name: Aidan's iPhone Backup display name: Aidan's iPhone Backup date: 02/07/2019 11:33:41 Backup size: 104258399691 bytes Backup encrypted: True Product version: 12.3.1 Product type: iPhone11,6 Serial number: FK1XH•••KPH6 Phone Number: +44 •••• •••••• ICCID: 894411••••••••••••5 MEID: 35728209••••••
Of course, whilst the iOS device's UDID is unique, there may be more than one backup of it on your computer -- for instance, if you have an archived backup -- like so:
$ rictl backup search -l | grep B919 DB72CB76A00CB81675F19907D4AC2B298628D83C 09/06/2014 13:57:08 7.1.1 iPhone6,2 ok /Users/afit/Library/Application Support/MobileSync/Backup/backup1 DB72CB76A00CB81675F19907D4AC2B298628D83C 23/07/2014 12:37:55 8.0 iPhone6,2 ok /Users/afit/Library/Application Support/MobileSync/Backup/backup2 DB72CB76A00CB81675F19907D4AC2B298628D83C 28/07/2014 12:43:56 8.0 iPhone6,2 ok /Users/afit/Library/Application Support/MobileSync/Backup/backup3
$ rictl backup info -u DB72CB76A00CB81675F19907D4AC2B298628D83C Multiple backups found with UDID DB72CB76A00CB81675F19907D4AC2B298628D83C. Use the '--search-path' option to specify the backup's location. This can be shown with the '-l' argument on 'rictl backup search'.
What's the solution? Narrow the search path by specifying the folder that the backup is in, rather than the folder containing the backup's folder!
$ rictl backup info -s /Users/afit/Library/Application Support/MobileSync/Backup/backup3 -u DB72CB76A00CB81675F19907D4AC2B298628D83C UDID: DB72CB76A00CB81675F19907D4AC2B298628D83C Path: /Users/afit/Library/Application Support/MobileSync/Backup/backup3 Backup in progress: False Device name: Aidan's iPhone Backup display name: Aidan's iPhone Backup date: 28/07/2014 12:43:56 Backup size: 239001214 bytes Product version: 8.0 Product type: iPhone6,2 Serial number: C7KNG•••G5MV Phone Number: +44 •••• •••••• ICCID: 894411••••••••••••5 MEID: 35728209••••••
Using list to list files within an iOS backup
$ rictl help backup list Usage: rictl backup list [args] List files in a backup Available arguments: -u, --udid=VALUE backup UIUD -s, --search-path=VALUE path to search for backups (two directories deep) -p, --password=VALUE backup password -l use a long listing format -r, --pattern=VALUE file pattern (regex) --allow-in-progress allow use of in-progress backups -h, --help show this message and exit
Let's try it out:
$ rictl backup list -u 00000000-0000000000000000 -r plist$ -l rw-r--r-- 321 24/06/2019 13:04:37 ManagedPreferencesDomain\mobile\.GlobalPreferences.plist rw------- 16975 21/06/2019 14:52:54 AppDomainPlugin-com.apple.stocks.widget\Library\Preferences\com.apple.stocks.widget.plist rw-r--r-- 219 01/07/2019 09:37:24 HomeDomain\Library\UserNotifications\A4CCFF5B-F963-425F-8068-729972F77C67\DeliveredNotifications.plist ...
Using extract to extract files from an iOS backup
$ rictl help backup extract Usage: rictl backup extract [args] Extract files from a backup Available arguments: -u, --udid=VALUE backup UIUD -s, --search-path=VALUE path to search for backups (two directories deep) -p, --password=VALUE backup password -o, --output-path=VALUE path to extract files to -r, --pattern=VALUE file pattern (regex) --allow-in-progress allow use of in-progress backups -h, --help show this message and exit
Let's extract all .db files from a backup to a folder named Extracted, and offer up a backup password of password:
$ rictl backup extract -u 00000000-0000000000000000 -r "\.db" -o "Extracted" -p "password" Extracting HomeDomain/Library/Voicemail/voicemail.db Extracting HomeDomain/Library/Safari/Bookmarks.db Extracting RootDomain/Library/Caches/locationd/consolidated.db Extracting WirelessDomain/Library/CallHistory/call_history.db ...
Using export to export data from an iOS backup
$ rictl help backup export Usage: rictl backup export [args] Export data from a backup Available arguments: -u, --udid=VALUE backup UIUD -s, --search-path=VALUE path to search for backups (two directories deep) -p, --password=VALUE backup password -t, --type=VALUE data type (messages, whatsapp, viber, kik, wechat, line, hike, tinder, photos, videos, recordings, contacts, calendar, notes, calls, locations, voicemail) -o, --output-path=VALUE associated file output path -r, --pattern=VALUE search pattern (regex) -f, --force allow overwriting exising files --allow-in-progress allow use of in-progress backups -h, --help show this message and exit
Exported data is made available in the same JSON format that ricloud API uses, and those formats are documented here.
Let's extract all message data from a backup. This data would be returned on the console's standard output stream (stdout), so we're going to redirect it to a file named messages.json. We'll save any associated files in a folder named Associated files, and offer up a backup password of password:
$ rictl backup export -u 00000000-0000000000000000 -t messages -o "Associated files" -p "password" > messages.json ...
$ cat messages.json [ { "From": "789789", "To": "Me", "Date": "2012-12-17T14:12:30Z", "Deleted": false, "Message": "All done! You're now on our Big Data Texts Tariff. We switched you over on 17/12/12", "Attachments": [] }, { "From": "789789", "To": "Me", "Date": "2012-12-17T18:12:50Z", "Deleted": false, "Message": "You have 300 Texts and Unlimited data", "Attachments": [] }, ...
Working with devices
$ rictl help device Usage: rictl device <command> [args] Work with devices over USB and Wi-Fi Available commands: search Show connected devices over USB and Wi-Fi backup Backup a connected device restart Restart a connected device shutdown Shutdown a connected device Use 'rictl help device <command>' for detailed help on a particular device command
When working with devices, there are four options: search, backup, restart, and shutdown.
Adding rictl to your path
iPhone Backup Extractor can automatically add rictl to your Windows or macOS computer's path, using the Preferences pane, so that it can easily be used in any terminal on your computer.
However, you can also set the path yourself, or use an alias command. rictl's functionality is accessed through iPhone Backup Extractor's binary, as the wrapper script shows:
$ cat `which rictl` #!/bin/bash /Applications/iPhone\ Backup\ Extractor.app/Contents/MacOS/iPhoneBackupExtractor cli "$@"
Common regular expression patterns for file searches
- Finding paths that end with the text
plist:-r plist$ - Finding paths with the file extension
.db:-r \.db
Enterprise use
Capabilities for rictl broadly follow those of iPhone Backup Extractor: the tool permits unrestricted operation for exploring backups, but will only extract up to four files or export four items of data at a time each time it is run.
We're keen to hear about how the technology is put to use, and support a number of businesses that have built their internal management or compliance tools or products on top of this technology. Please get in touch with us if this might be valuable for you.
