A User Guide

Looking for something specific? The User Guide and FAQ are indexed within the app — open Apparency, click on the Help menu (Command-?), and type in the Search field. Results listed under Help Topics link directly to the appropriate User Guide section or FAQ entry here.

Opening an App in Apparency

general info

There are several ways to open an app using Apparency:

If you don't see the Open With Apparency item in the Services menu or in the Finder context menu, choose Finder > Services > Services Preferences, go to the Development group, and make sure that Open With Apparency is checked. You can also add a keyboard shortcut here, if you wish, but that's not necessary to make the menu item appear.

Whichever method you choose, Apparency opens a new window, showing the app itself, along with any components inside it: Apparency main window

You can actually open any macOS bundle with Apparency, including an app plug-in or a system framework. You can also open a “bare” executable file, such as one found in /usr/local/bin. A bare executable can have many of the same attributes as a bundle, and can even have an embedded Info.plist.

Examining the App Structure

The browser, on the left side of the main Apparency window, shows the basic structure of the app: examining app structure

At the top of this view is the app itself. Most apps also contain other components inside them — frameworks, plug-ins, app extensions, Spotlight importers and so on. These components are shown underneath the main app, using a hierarchical view similar to the Finder's List view. If any of the components contain sub-components, use the disclosure button to expand these further.

Apparency doesn't show all of the individual files inside the app bundle. The Finder is a better tool for navigating files: control-click the app icon and choose Show Package Contents.

Rather, Apparency shows bundles — and bare executables — that are found in specific places within the app, as defined by macOS. For example, macOS requires app extensions to be placed in Contents/PlugIns, so that is one place that Apparency looks. The point is to show components that add to system functionality (as is the case with app extensions, for example), as well as those that are simply part of the app's internal organization (such as frameworks).

By default, Apparency looks for components only in well-defined places, as defined by macOS, rather than examining every file and folder inside the app (which could become quite slow for large apps). However, this may miss components, which sometimes live in other places, such as the Resources folder. If you want Apparency to try harder to find components, when you select the app in the File > Open dialog, check Look for components in de facto “code places” before clicking Open. If the app is already open in Apparency, use File > Re-open with Options to quickly re-open it.

The columns of the browser show some basic information about the app, and any components:

Click on the Name, Kind or Version column title to re-order the components accordingly. This can be useful for an app with a large number of components.

Getting Information About a Component

The info pane, on the right side of the main Apparency window, shows information about the app or other component that is currently selected in the browser: show component info

General Information

In the top part of the info pane, Apparency shows general information about the app or component:

general info

Most of these attributes can be selected, and thus copied. Unfortunately, this can make the cycling attributes, such as Kind, a bit squirrelly to work with. If you single-click, Apparency will still cycle through the different values. If you double- or triple-click, Apparency will instead enter selection mode, with the appropriate select-word or select-all behavior. If you want to get out of selection mode, so that the attribute values cycle again, press the Escape key. Or click on the label for the attribute, instead of the attribute value: this will always cycle the attribute, regardless of selection state.

Document Types and Other Info.plist Properties

In the middle part of the info pane, Apparency shows a summary of the file and other types that the app provides to macOS, via its Info.plist file:

document type info

For each of these, Apparency simply shows how many of each type is found (because it is difficult to summarize the contents in any succinct way). To see the actual definitions, click the link to Info.plist button button in front of the number: this will show the Info.plist, with the appropriate property selected and expanded.

Code Signature, Sandbox and Gatekeeper Info

In the lower part of the info pane, Apparency shows the status of the code signature and other security features:

signature info

Note that you can select more than one component in the browser. When you do this, the info pane will show the information that is identical for all of the selected components. This is a quick way to determine if multiple components support the same processor architectures, or have the same code-signing identity, for example. Any attributes that have different values for one or more of the selected components will show Multiple values instead.

Getting Details About a Component

While the info pane gives you a summary of the selected app or component, there are buttons in the toolbar that allow you to see more details. (Some of these are also available through buttons in the info pane itself; use whichever one is more convenient.)

Show the Code Signature

If the selected app or component was signed, click the Signature toolbar button Signature toolbar button (or use Cmd-Shift-S) to see the actual signing certificate and other details about the verification of the signature (including the applicable Gatekeeper policy, as discussed above). signature and trust dialog

Click the Show Certificate button to examine the certificate that created the signature, and the entire chain up to the Certificate Authority, which is typically the Apple Root CA. Select an individual certificate in the chain, and click the disclosure arrow next to Details to see more information.

You can also export a certificate by dragging the certificate icon (from the lower pane) and dropping it in the Finder. This will give you a DER-format file that you can open with Certificate Assistant, or manipulate with command-line tools like security(1) or openssl(1).

Show the Info Property List

The information property list — or simply, the Info.plist — contains a number of Apple-defined properties. These tell macOS how the app or component works, what it can do, what icon to show, what documents it can handle, and many other things. Apparency extracts a few interesting bits of the Info.plist to show in its info pane — such as the version information, the bundle identifier, and so on — but you may still want to examine the Info.plist in its entirety.

Click the Property List toolbar button Property List toolbar button (or use Cmd-Shift-I) to view the Info.plist file for the selected app or component: Info.plist view

Most of the Info.plist keys have some sort of documentation on Apple's Developer site: to jump directly to that documentation, select a row and click Open Apple Documentation for Key. (If this button is disabled, Apparency doesn't have a direct link for that key, either because the key isn't documented or because we didn't find the documentation to index it.) Alternatively, when you move the pointer over a key name, if a link button link to documentation button appears on the right side, clicking this will also take you to the documentation for that property.

If you're looking for a particular key or value, click in the search field (or use Cmd-F) and type the text you want to find. Apparency will show only the rows that match, or for arrays or dictionaries, the rows that contain matches. Click the search options button search options button to choose between searching keys and values, or to restrict the way that text matches. Click the cancel button cancel search button to return to viewing the unfiltered Info.plist.

Show the Entitlements

The entitlements of an app or component enumerate specific capabilities that the component requires to do its work. macOS grants (or denies) these capabilities to the app or component, based on the entitlements and (sometimes) other restrictions. Entitlements take several forms:

Click the Entitlements toolbar button Entitlements toolbar button (or use Cmd-Shift-E) to view the entitlements for the selected app or component: entitlements view

As described above for the Info.plist, documentation links to Apple's Developer site are available for some entitlement keys.

Likewise, you can use the search field to filter entitlements on specific key or value text.

If the selected app has a provisioning profile, as discussed below, there will be an additional entitlements view provisioning column header column that shows whether each entitlement is allowed by the profile. See here for a description of each possible entitlement provisioning status.
Apparency can also show a “merged” view of all entitlements requested by all of the components of an app. This can be helpful to get an overall sense of what the app will do, especially when creating a Privacy Preferences Policy Control (PPPC) Profile. Use File > Show Entitlements for All Executables (Cmd-Control-A) to view the merged entitlements: these are explained further in the FAQ.

Show Executable Information

Apparency can show details about the executable file associated with an app or component. Click the Executable toolbar button Executable toolbar button (or use Cmd-Shift-X) to view this information for the selected component. (If the button is disabled, the component either doesn't contain an executable — i.e. the component contains resources but no code — or the executable is not a native Mach-O type, which is possible but atypical.) executable view

The information shown for an executable is mostly of the sort you would otherwise need the otool(1) or objdump(1) tools to access:

Show App Store Receipt

An app installed from the App Store usually has an embedded receipt file. This receipt is signed by Apple, and can be used by the app to verify that it was actually purchased by the current user (or by another user sharing the same computer). The receipt can be inspected to see additional App Store and purchase information.

Click the Receipt toolbar button Receipt toolbar button (or use Cmd-Shift-T) to view the App Store receipt for the selected app: App Store receipt view

The information shown for an App Store receipt is as follows:

Show Provisioning Profile

Certain apps — depending on their capabilities and how they're distributed — will have an embedded provisioning profile. This is essentially “permission” from Apple for

The provisioning profile must be signed by Apple, which allows Apple to restrict what an app can do and where it can run — even if the app itself is signed by a third-party developer and distributed outside of the App Store.

Generally, the developer creates a provisioning profile through the Apple Developer Program website (or allows Xcode to do so automatically). Some capabilities are allowed routinely — without, one assumes, any human intervention. Other capabilities — such as Endpoint Security extensions or DriverKit drivers — are subject to an Apple approval process. Either way, the app can't use these capabilities without a matching, Apple-signed provisioning profile.

The provisioning profile scheme originated on iOS, where the specification of devices is more meaningful: this is the mechanism by which an iOS app can be installed directly onto a limited number of registered test devices (without going through the App Store). It's possible to use a provisioning profile on macOS to limit an app to running on specific Macs, but this is probably far less common.

Note that not all macOS apps have or require a provisioning profile. If an app doesn't use any of the restricted capabilities, it doesn't need a provisioning profile. Also, an app from the App Store is automatically trusted to use the capabilities found in its entitlements — presumably since these were vetted through App Review before the app was posted on the App Store. Likewise, Apple's own apps — those built into macOS or distributed from the Apple website — don't require provisioning.

macOS enforces the provisioning rules when you open an app: if the app is not from Apple or from the App Store, and if it uses any restricted capabilities, it must have a matching, Apple-signed provisioning profile. If the profile is missing, is invalid or lacks the required capabilities, the app will crash immediately.

With that background, click the Provisioning toolbar button Provisioning toolbar button (or use Cmd-Shift-P) to view the provisioning profile for the selected app: provisioning profile view

The information shown for a provisioning profile is as follows:

Show Launchd Configuration

Historically, in order to activate a macOS daemon or agent, a launchd job definition property list had to be installed into /Library/LaunchDaemons or /Library/LaunchAgents, often via a macOS Installer package. But over the years, macOS has acquired other methods of activating daemons and agents.

Way back in Mac OS X 10.6 (Snow Leopard), the SMJobBless() API added a way to for apps to install privileged helper applications. This is essentially a launchd daemon, but delivered in the app bundle at Contents/Library/LaunchServices. After administrator authentication, the executable is copied to /Library/PrivilegedHelperTools. The executable must have an embedded launchd job definition template, which macOS uses to create a plist in /Library/LaunchDaemons.

Fast forward to macOS 13 (Ventura), where the SMAppService API introduces another way for apps to bundle and install launchd daemons or agents. In this case, the launchd job definition plists are delivered in the app bundle at Contents/Library/LaunchDaemons or Contents/Library/LaunchAgents, and point to a daemon or agent executable elsewhere in the bundle (using a new BundleProgram key). This new scheme appears to be “native” to launchd, in that the job definition plist and executable are both used directly from their place in the app bundle, and one can see the bundle information in launchctl(1) print output.

To help you see where apps leverage these mechanisms, Apparency looks for the above artifacts within the app, and gives the daemon or agent executable components a special Kind: “Privileged helper application” for the older scheme, or “Background app service daemon” or “Background app service agent” for the new one. In each case, you can select the component and use Component > Show Launchd Configuration to examine the associated launchd job definition plist. Apparency works out the differences in the way that the two schemes handle these plists, and always presents them along with the executable that they reference.

With the macOS 13 scheme, it is theoretically possible for there to be multiple launchd jobs that share a single executable. If Apparency finds such a scenario, you will see a submenu under the Show Launchd Configuration menu, where you can select which one to inspect.

Examining Components in Other Apps

If you want to examine a component beyond what Apparency shows, there are a few ways that Apparency tries to make this easier.

In the Finder

Occasionally, you may want to see a specific component in the Finder; for example, to look at the individual files that it contains. You can do this easily from Apparency: select the component in the browser, and click the Show in Finder toolbar button Show in Finder toolbar button (or use Cmd-Shift-R).

In the Terminal

Alternatively, if you want to examine a component in the Terminal, you can select it and choose Edit > Copy Path for Component (Cmd-Shift-C). Then you can paste that path into the Terminal, or wherever.

If you want to show — or copy the path to — the main executable, instead of the component itself, hold down Option while doing the above.

Previewing with Quick Look

Sometimes, a component has a kind that will yield an illuminating Quick Look preview. Select the the component and choose Component > Quick Look Component (Cmd-Y) — or just press the spacebar, as in the Finder.

This is probably mostly useful when the component is actually some sort of script (Bash or Python or what have you), and thus will produce its source text upon previewing. Apps might bundle scripts for various reasons, but note that you might need to enable searching in de facto “code places” in order to see such scripts as components in Apparency (since they tend to live in Resources directories).

If you have any other Quick Look Preview extensions installed, you might get useful previews for other kinds of components. Of course, for most kinds of components — applications, executables and standard bundles like frameworks — the Quick Look preview will be generated by Apparency itself, and isn't going to tell you anything new!

Finding App Containers

If an app uses the App Sandbox, it is not allowed to read or write arbitrary files within your home folder — it gets permission only for files that you pick through an Open or Save dialog, or to files or folders declared in its entitlements. Otherwise, it is expected to work totally within its app container.

For each sandboxed app (or other sandboxed component), macOS creates an app container under your Library > Containers folder. The container folder is named after the app's bundle identifier, and within its Data subfolder, contains a structure much like a normal home folder — macOS actually tells the app that this is your home folder.

What actually winds up in this container depends on the app. Preference settings almost always wind up here (instead of in the normal Library > Preferences folder). A “document-based” app — that is, an app which offers File > Open and File > Save, such as Pages or Keynote — will still put files where you tell it (not inside the app container). But a so-called “shoebox” app — one that handles content more abstractly than at the file level, like Photos or Notes — may use the app container more substantively (although often the canonical content might be stored in iCloud).

Anyway, most of the time you can ignore the app container, but especially when debugging an issue, it can be helpful to inspect it. Apparency tries to make this a bit easier by helping you find the app container: select the app or other component, and click the Show Container toolbar button Show Container toolbar button (or use Cmd-Shift-A).

Alternatively, if you want to examine the container in the Terminal, you can select the component and choose Edit > Copy Path for App Container (Cmd-Shift-K).

Note that individual components other than the top-level app might also have their own app containers. For example, the app might contain a Share Extension or a Quick Look Preview Extension, and these are required to be sandboxed also. Any such sandboxed component will have a separate app container.
Because Apparency itself is sandboxed, it can't access other app's containers — or indeed, anything outside of its own app container. As such, it doesn't really know if the selected component's app container exists, only that the component is sandboxed and where the app container would be. It asks the Finder to show where the app container would be, but it is possible there will be nothing there, since macOS doesn't create the app container until the component is first used.

Finding Shared App Group Containers

Because different sandboxed apps have different app containers, two apps — even two apps in a suite from the same developer — can't share data in their respective app containers. Indeed, even an app and another component within that same app — such as a Share Extension — can't share data in the app container.

Apple's answer to this problem is the app group container. This is a secondary container that can be accessed by two or more components, as long as they are from the same developer. The developer defines a group container identifier through the Apple Developer Program website (or through Xcode), and allows individual apps or components to use that group container via the entitlement. A single group container can be shared amongst any number of components, and a component can have access to any number of group containers: this is all up to the developer to decide.

macOS creates group containers under your Library > Group Containers folder. Each group container folder is typically named with the developer's Apple-issued team ID, following by the developer-chosen group identifier. (Apple apps tend not to follow this pattern, using a group. prefix, or none at all.) Unlike the app container, the structure of the group container is not standardized, so the developer can organize it in whatever way they choose. (However, if the group container is used to share preferences, you will likely find a Library > Preferences folder inside.)

As with the app container, you can use Apparency to find a group container. Select the app or other component, and use Component > Show Group Container X in Finder. (The choices in the Component menu will depend on the selected component and what groups it has access to; if you don't see any Show Group Container items, there are no groups for that component.) Alternatively, to examine the group container in the Terminal, use Edit > Copy Path for Group Container X.

Using From Quick Look

Apparency provides a Quick Look Preview extension, which adds a bit more information to the standard macOS preview for apps.

The Apparency preview works in any normal Quick Look context. For example, if you open a Finder window to your Applications folder and choose View > as Gallery or View > Show Preview, you'll get an enhanced preview for the selected app: Quick Look preview

Apparency tries to fit the preview into the space available for it — although macOS makes us guess about this, so you may need to resize the preview pane to see some information.

Note that the information in the Quick Look preview is only for the top-level app that you select; it doesn't consider any components within it. Click the Open With Apparency button to quickly open the app in Apparency, where you can see all the details.