Using rictl to work with backups on the command line

Updated

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, stdout streams of exported data)
  • Support for multiple simultaneous search paths
  • Support for all formats of encrypted backup
  • Support for relative and home-based (~) paths

klzzwxh:0002 shown in macOS Terminal
rictl shown in macOS Terminal

klzzwxh:0004 shown in Windows Command Prompt
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

Use 'rictl help <command>' for detailed help on a particular command

At present, rictl exposes a backup mode for working with local backups.

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:

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
  • -s can 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": []
  },
...

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.

iPhone Backup Extractor's "Scripting" preferences pane
iPhone Backup Extractor's "Scripting" preferences pane

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. This can be obviated by running the tool multiple times.

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.

How can we help?

Our support team are here to help!

Our office hours are Monday to Friday, 9 AM to 5 PM GMT. The time is currently 6:52 AM GMT.

We aim to reply to all messages within one working day.

Go to support section › Contact support ›
Our awesome support team

Can we improve this article?

We love hearing from users: why not drop us an email, leave a comment, or tweet @reincubate?

© 2008 - 2019 Reincubate Ltd. All rights reserved. Registered in England and Wales #5189175, VAT GB151788978. Reincubate® is a registered trademark. Privacy & terms. We recommend 2FA. Built with in London.