Setup
Information about different Butler setup steps.
Butler adapts to what access is available. While all permissions are optional, if you don't grant any permissions, most features will not work. Butler tries to work with as few permissions as possible. If a permission is missing, you will see a prompt to grant the missing permission or complete the required setup step.
Butler will automatically try to complete some of the setup steps if root or Shizuku is available.
Some permissions overlap or are supersets of each other, e.g. you can give Butler access to both Root and Shizuku. Butler will always try to use the best possible access method for any action, and if that fails, retry with the second best access method and then third best etc.
The "manage storage" permission is a broadly scoped storage access permission. It is required for almost all file operations.
- On Android 12 and earlier it grants access to all public storage.
- On Android 13+ it still grants access to all public storage, but not to sub-directories under
Android/data.
Usage statistics permissions give Butler access to data, cache sizes and if an app is running or when it was last used.
Butler uses the Android Storage Access framework (SAF) to gain access to additional storage areas. Butler will ask you to grant access to specific paths that are not accessible by just having the "Manage storage" permission (Just Android Things™️).
- Press the
Grant accessbutton - A new window opens
- If the correct path is already selected, otherwise you have to navigate to the path that Butler wants.
- Then press the
Use this folderbutton, the setup entry for this path will unlock and be colored green.
For when things don't go as planned.
Granting access to Android/data|obb is not possible with newer versions of the system's Files app (com.google.android.documentsui) on Android 11 and Android 12. If the installed Files app targets Android 14 (API-level 34) or newer, then Butler will hide the SAF access request for these paths (like on Android 13+).
Google Play updates the Files app through the Google Play system update service. The original "Files" app (build for API-level 31, e.g. aml_doc_310851020 (310851020)) that came with Android 12 OS, allows Butler to open the SAF path selection window on Android/Data while the latest "Files" app (build for API-level 34 or later, e.g. 14-10492947 (340916000)) prevents this.
Workaround:
You can uninstall the update to the Files and then set up Butler. Updating the Files app again will not break already granted permissions.
- Open device settings
- Go to "Apps & notifications" or "Application Manager"
- Find the
Filessystem app - Tap on the three-dot menu, usually on the top right corner
- Choose "Uninstall updates"
or
adb uninstall com.google.android.documentsui
Granting access to paths via the Storage Access Framework requires an app that lets the user confirm the paths to which access will be granted. This app is the "Documents" app. It's a system app that is built into every Android device since Android 5.0 (com.android.documentsui or com.google.android.documentsui). If you get this error, then either someone deleted or disabled this app. In most cases someone ran an overzealous "de-bloating" tool that disabled it. You can re-enable it via ADB:
adb shell pm enable com.android.documentsui
or
adb shell pm enable com.google.android.documentsui
If the window used to grant access to paths is empty, then your external storage provider package (com.android.externalstorage) is maybe disabled (likely through an overzealous "de-bloating tool). You can re-enable it via ADB:
adb shell pm enable com.android.externalstorage
Running the Google Play system update again will restore the update. You can also manually download an updated version from APKMirror.com.
Without this permission Butler won't be able to post notifications. On some ROMs this may negatively affect reliability when executing in the background.
Butler requires the permission QUERY_ALL_PACKAGES to check which apps are installed on your device (i.e. "visibility into the inventory of installed apps"). Also see "Usage Stats Permission"
The QUERY_ALL_PACKAGES permission is required to show details about installed apps and their files.
This permission exists since Android 11 and is normally granted by default. Since Android 14 some devices (e.g. #1015, #1354) exist where the permission is not granted by default or can be revoked.
With root access, Butler has full access to your device and you can browse any location and file. Usually this means that you unlocked your bootloader and set up Magisk.
If Butler thinks that your device may be rooted, then Butler will ask for root access first. If root access is granted, Butler will use the root access to grant as many of the other permission as possible. Root access is the highest level of access you could give an app, the other permission are then only required for ease of use and performance, which is why they don't require extra consent during setup if Butler already has root.
Shizuku is a special app that you can install and set up that can be used to grant elevated access/permissions to apps. It is a modification you can make to your phone that other apps can take advantage of.
It's similar to root, but not the same. The permissions are slightly less powerful, but the modification is not permanent and doesn't require you to unlock your bootloader.
The user manual to set up Shizuku can be found here.
After you have set up Shizuku:
- Give consent for Butler to use Shizuku. This is internal to Butler, you can use it to enable/disable Butler's use of Shizuku
- After giving consent, a
Grant accessdialog from Shizuku should show - Confirm the dialog
- Butler should display a new status indicator that show whether Butler can connect to the Shizuku service
Setting up Shizuku, if you already have granted Butler Root access doesn't enable additional features, but improves reliability. If actions fail with Root permission, then Butler will retry with Shizuku.
You can check Butler's Shizuku status by going to Settings > Setup and viewing the Shizuku setup card. It should say Shizuku link is ready. If it says Waiting for link with Shizuku check that the Shizuku app itself is working, it might need to be set up again.