# Top-level properties

The following keys are used at the top level of the [config](https://www.popclip.app/dev/config.md) to
define properties of the extension itself. All properties are optional except
`name`.

| Key                       | Type                 | Description                                                                                                                                                                                                                                                                                                                           |
| ------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` (Required)         | String (Localizable) | A short, human-readable display name for this extension.                                                                                                                                                                                                                                                                              |
| `icon`                    | String               | See [Icons](https://www.popclip.app/dev/icons.md). If you omit this field, the icon for the first action will be used (if any), or else no icon will be displayed.                                                                                                                                                                    |
| `identifier`              | String               | You may provide a string to uniquely identify this extension. See [The `identifier` field](#the-identifier-field).                                                                                                                                                                                                                    |
| `description`             | String (Localizable) | A short, human readable description of this extension. Appears in the [directory](https://www.popclip.app/extensions/) but not in the app.                                                                                                                                                                                            |
| `keywords`                | String               | Space-separated words to help people find your extension in the [directory](https://www.popclip.app/extensions/), whose search matches case-insensitively against the name and keywords but not the description.                                                                                                                      |
| `macosVersion`            | String               | Minimum macOS version needed by this extension. For example `14.0`.                                                                                                                                                                                                                                                                   |
| `popclipVersion`          | Integer              | Minimum PopClip version required. This is the integer build number e.g. `4151`. Specifying the current PopClip version here can help preserve your extension's functionality in future, because PopClip applies backward-compatibility rules for old extensions.                                                                      |
| `options`                 | Array                | Array of dictionaries defining the options for this extension, if any. See [Options](https://www.popclip.app/dev/options.md).                                                                                                                                                                                                         |
| `entitlements`            | Array                | Only applies to JavaScript extensions. The possible values are `network` (allows use of XMLHttpRequest), `dynamic` (allows dynamically generated actions) and `script` (allows [calling external scripts](https://www.popclip.app/dev/external-scripts.md)). The `dynamic` entitlement cannot be combined with `network` or `script`. |
| `action` or `actions`     | Dictionary or Array  | A dictionary or array of dictionaries defining the action(s) for this extension. See [Action properties](https://www.popclip.app/dev/actions.md).                                                                                                                                                                                     |
| `submenu`                 | Array                | Makes the extension a single button that opens a submenu of child actions. See [Submenus](https://www.popclip.app/dev/actions.md#submenus).                                                                                                                                                                                           |
| `showAs`                  | String               | Sets the default presentation of the extension's actions in the PopClip bar: `icon` or `text`. If omitted, the default is `icon`. (The user can override this per action.)                                                                                                                                                            |
| `authServiceLabel`        | String (Localizable) | For extensions with a sign-in (`auth` function): a label identifying the service to which the user is being asked to sign in. Used in UI prompts like _Sign in to your [label] account_. If omitted, the extension name is used.                                                                                                      |
| `authKeychain`            | String               | For extensions with a sign-in (`auth` function): which keychain the sign-in secret goes in. `sync` (the default) shares one sign-in across the user's devices via iCloud Keychain; `local` keeps it on the Mac where the user signed in, so each device signs in separately.                                                          |
| `offersMultipleInstances` | Boolean              | Controls whether PopClip enables the Duplicate and New Instance commands for this extension. By default, PopClip allows multiple instances if the action has any options. Setting this property will override the automatic behavior.                                                                                                 |
| `shellScriptRationale`    | String               | A brief explanation of why the extension needs a [Shell Script action](https://www.popclip.app/dev/shell-script-actions.md) instead of JavaScript. Not used by the app; required when [submitting](https://www.popclip.app/extensions/submit.md#shell-script-policy) an extension with a Shell Script action to the directory.        |

## The `identifier` field

An identifier may contain only alphanumeric characters (`A-Z`, `a-z`, `0-9`),
period (`.`), and hyphen (`-`).

A good identifier should be globally unique so as not to clash with other
creators. Use your own prefix, which could be a reverse DNS-style prefix based
on a domain name you control, such as `com.example.myextension`. Alternatively,
just pick something likely to be unique to you.

If you don't provide an `identifier`, PopClip will identify the extension by the
package directory name (e.g. `Name.popclipext`) if it's a package extension, or
the `name` if it's a snippet.

**Warning: Reserved identifier**

The identifier prefix `com.pilotmoon.` is reserved for signed extensions
published by me. If you try to use it for your own extensions, you'll get an
error.