Interface PopClip

This interface describes the methods and properties of the global popclip object.

interface PopClip {
    appear(): void;
    context: Context;
    copyContent(content, options?): Promise<void>;
    copyText(text, options?): Promise<void>;
    input: Input;
    modifiers: Modifiers;
    openTemplateUrl(urlTemplate, query, options?): Promise<void>;
    openUrl(url, options?): Promise<void>;
    options: Options & AuthOptions;
    pasteContent(content, options?): Promise<void>;
    pasteText(text, options?): Promise<void>;
    performCommand(command, options?): Promise<void>;
    pressKey(key, modifiers?, options?): Promise<void>;
    pressKeys(sequence, options?): Promise<void>;
    revealFile(path): void;
    runAppleScript(source, options?): Promise<AppleScriptResult>;
    runAppleScriptFile(path, options?): Promise<AppleScriptResult>;
    runShortcut(name, options?): Promise<AppleScriptResult>;
    settingsRequiredError(message?): Error;
    share(serviceName, items): Promise<void>;
    showFailure(): void;
    showSettings(): void;
    showSuccess(): void;
    showText(text, options?): void;
    signInRequiredError(message?): Error;
}

Properties

`Readonly` context

context: Context

The current context.

`Readonly` input

input: Input

The current selection.

`Readonly` modifiers

modifiers: Modifiers

The state of the modifier keys when the action was invoked in PopClip.

During the execution of the population function, all the modifiers will read as false.

`Readonly` options

options: Options & AuthOptions

The current values of the options.

Methods

appear

appear(): void
Trigger PopClip to appear again with the current selection.

Returns void
- Defined in popclip.d.ts:1095

copyContent

copyContent(content, options?): Promise<void>
Place mixed content on the pasteboard, optionally showing "Copied" notification to the user. Same promise semantics as copyText.
Parameters
- content: PasteboardContent
- Optional options: CopyOptions
Returns Promise<void>
- Defined in popclip.d.ts:1004

copyText

copyText(text, options?): Promise<void>
Place the given string on the pasteboard, optionally showing "Copied" notification to the user.

Returns a promise that resolves once the items are committed to the pasteboard, and rejects if the pasteboard refuses the write.
Parameters
- text: string
  The plain text string to copy
- Optional options: CopyOptions
Returns Promise<void>
- Defined in popclip.d.ts:998

openTemplateUrl

openTemplateUrl(urlTemplate, query, options?): Promise<void>
Fill a query into a template URL and open it. This is the mechanism used by URL actions, exposed to JavaScript.

The query is trimmed of surrounding whitespace and URL-encoded, then substituted into the template in place of the placeholders *** and {popclip text}. Any {popclip option <name>} placeholders are replaced with the URL-encoded values supplied in the options sub-dictionary. The resulting URL is then opened as by openUrl, and that open's promise is returned.

When the copy option is set, the query text is also copied to the clipboard.
Parameters
- urlTemplate: string
  The URL template containing placeholders.
- query: string
  The text to substitute into the template's query placeholders.
- Optional options: {
      activate?: boolean;
      app?: string;
      backgroundTab?: boolean;
      clean?: boolean;
      copy?: boolean;
      options?: {
          [key: string]: string;
      };
      plus?: boolean;
      verbatim?: boolean;
  }
  Options.
  - Optional activate?: boolean
    Whether to request that macOS activate the target app. (Default: true)
  - Optional app?: string
    Bundle identifier of the app to open the URL with. For example "com.google.Chrome".
  - Optional backgroundTab?: boolean
    When opening a web URL in a supported browser, whether to open the URL in a background tab. (Default: false)
  - Optional clean?: boolean
    Collapse runs of internal whitespace in the query to a single space. Mirrors the clean query property of URL actions. (Default: false)
  - Optional copy?: boolean
    Whether to copy the query text to the clipboard, overriding the app's default behaviour for this call.
  - Optional options?: {
    [key: string]: string;
    }
    A mapping of option names to values, used to fill any {popclip option <name>} placeholders in the template.
    - [key: string]: string
  - Optional plus?: boolean
    Encode spaces in the query as + instead of %20. Some search engines (for example Amazon) expect this format. Mirrors the spaces as plus property of URL actions. (Default: false)
  - Optional verbatim?: boolean
    Wrap the query in double quotes for an exact-phrase search. If unspecified, defaults to the state of the Option (⌥) key when the action was invoked.
Returns Promise<void>
Example
```
popclip.openTemplateUrl("https://www.google.com/search?q=***", popclip.input.text);
```
- Defined in popclip.d.ts:1356

openUrl

openUrl(url, options?): Promise<void>
Open a URL in a browser or other application.

If a target application bundle identifier is specified via the app option, PopClip will ask that app to open the URL.

If no target app is specified:
- If the URL is a web URL (http or https scheme) and the current app is a browser, the URL is opened in the current app.
- Otherwise, PopClip asks macOS to open the URL in the default handler for its scheme.
Any parameters etc. in the URL must be appropriately percent-encoded. JavaScript provides the encodeURIComponent() function for this. Alternatively you can use the URL class, which is available as a global in PopClip's JavaScript environment.

Returns a promise that resolves once the request has been delivered to the browser or OS.
Parameters
- url: string | UrlObject
  URL string or a UrlObject representing the URL to open.
- Optional options: {
      activate?: boolean;
      app?: string;
      backgroundTab?: boolean;
  }
  Options.
  - Optional activate?: boolean
    Whether to request that macOS activate the target app. (Default: true)
  - Optional app?: string
    Bundle identifier of the app to open the URL with. For example "com.google.Chrome".
  - Optional backgroundTab?: boolean
    When opening a web URL in a supported browser, whether to open the URL in a background tab. (Default: false)
Returns Promise<void>
Example
```
// examples using string URLs
popclip.openUrl("https://xkcd.com"); // open in current/default browser
popclip.openUrl("https://xkcd.com", {app: "com.brave.Browser"}); // open in Brave browser

// example using URL class
const mailUrl=new URL("mailto:support@pilotmoon.com");
mailUrl.searchParams.append("subject", "What's up?");
popclip.openUrl(mailUrl); // the mailto: link will open in the default mail application
```
- Defined in popclip.d.ts:1317

pasteContent

pasteContent(content, options?): Promise<void>
Paste mixed pasteboard content. Same promise semantics as pasteText.
Parameters
- content: PasteboardContent
- Optional options: PasteOptions
Returns Promise<void>
- Defined in popclip.d.ts:985

pasteText

pasteText(text, options?): Promise<void>
If the target app's Paste command is available, this method places the given string on the pasteboard and then invokes the target app's Paste comand. If the restore flag is set in the options, it will then restore the original pasteboard contents.

If the target app's Paste command is not available, it behaves as copyText instead.
Parameters
- text: string
  The plain text string to paste
- Optional options: PasteOptions
Returns Promise<void>
Example
```
// place "Hello" on the clipboard and invoke Paste
await popclip.pasteText("Hello");
// place "Hello", then restore the original pasteboard contents
await popclip.pasteText("Hello", {restore: true});
```
Returns a promise that resolves once the paste command has been delivered to the app, after the pasteboard write was confirmed and — if restore is set — after the pasteboard was restored. It rejects if the write never appears on the pasteboard or the restore fails.
- Defined in popclip.d.ts:980

performCommand

performCommand(command, options?): Promise<void>
Invokes a command in the target app.

Returns a promise. For cut and copy it resolves once the app has placed the resulting content on the pasteboard and any transform has been applied. For paste it resolves once the once the command has been delivered to the app. An unknown command or transform value throws immediately, doing nothing.
Parameters
- command: "copy" | "cut" | "paste"
  Either cut, copy or paste.
- Optional options: {
  transform?: "none" | "plain";
  }
  Options for the command.
  - Optional transform?: "none" | "plain"
    Transformation to apply to the pasteboard contents. (Default: none)
    
    none: regular pasteboard operation
    
    plain: strips away everything but plain text
Returns Promise<void>
Example
```
await popclip.performCommand("copy")
```
- Defined in popclip.d.ts:1022

pressKey

pressKey(key, modifiers?, options?): Promise<void>
Simulate a key press by the user.
Parameters
- key: string | number
  The key to press. When this parameter is a string, PopClip will interpret it as in Key Press actions. When this parameter is a number, PopClip will use that exact key code.
- Optional modifiers: number
  An optional bit mask specifiying additional modifier keys, if any.
- Optional options: {
  target?: "session" | "app" | "hid";
  }
  Options for the key press.
  
  The target option says where PopClip posts the key events:
  - session (the default) posts to the session event tap, kCGSessionEventTap.
  - app posts to the process of the application PopClip is acting on, using CGEventPostToPid(). This is the only target aimed at a particular process, so the keys arrive there whatever holds keyboard focus at the time.
  - hid posts to the HID event tap, kCGHIDEventTap.
  Where the events go from a tap is up to the system. If a key combo does not have the effect you expect with one target, it is worth trying the others.
  - Optional target?: "session" | "app" | "hid"
Returns Promise<void>
A promise that resolves once the press has been made, and rejects if it fails. Await it when a later step depends on the press completing.
```
await popclip.pressKey('command c');
popclip.pressKey('command space', 0, { target: 'hid' });
```
To press a sequence of combos, with waits between them if needed, see pressKeys().
Examples
```
// press the key combo ⌘B
await popclip.pressKey('command B');
// press the key combo ⌥⌘H
await popclip.pressKey('option command H');
// press the return key
await popclip.pressKey('return');
await popclip.pressKey(util.constant.KEY_RETURN); // equivalent
// press option and the page down key
await popclip.pressKey('option 0x79');
await popclip.pressKey(0x79, util.constant.MODIFIER_OPTION); // equivalent
```
Some key code and modifier constants are available in util.constant.
- Defined in popclip.d.ts:1147

pressKeys

pressKeys(sequence, options?): Promise<void>
Simulate a sequence of key presses, with optional waits between them.

The sequence runs as one unit: PopClip makes the presses in order on its key-press queue, and no other press can interleave mid-sequence.
Parameters
- sequence: (string | number)[]
  The presses to make, in order. Each entry is a key press in the same form as pressKey()'s key parameter — a string such as 'command b' or a numeric key code — or a wait, written 'wait <milliseconds>' (up to 5000). If any entry does not parse, the call throws and nothing is pressed.
- Optional options: {
  target?: "session" | "app" | "hid";
  }
  The same options as pressKey(): target says where the presses are posted (session, the default, or app or hid).
  - Optional target?: "session" | "app" | "hid"
Returns Promise<void>
A promise that resolves once the whole sequence has run, and rejects if the presses could not be made.
```
// press ⌘space, give Spotlight a moment, then paste
await popclip.pressKeys(['command space', 'wait 100', 'command v'], { target: 'hid' });
```
- Defined in popclip.d.ts:1175

revealFile

revealFile(path): void
Show a file or folder in the Finder. A file is selected inside its enclosing folder; a folder is opened as the window's own root.

The path must be an absolute path on the user's disk — the kind found in popclip.input.data.paths.

Throws if the path is omitted or does not exist.
Parameters
- path: string
  An absolute path to an existing file or folder. A leading ~ is expanded to the user's home folder.
Returns void
Example
```
popclip.revealFile(popclip.input.data.paths[0]);
popclip.revealFile("~/Downloads");
```
- Defined in popclip.d.ts:1282

runAppleScript

runAppleScript(source, options?): Promise<AppleScriptResult>
Run an AppleScript, supplied as source text.

Requires the script entitlement, and may only be called during the action phase.

To call a specific handler (subroutine) in the script, name it in the options — see AppleScriptOptions.

Bad input throws immediately, and nothing runs. A script that runs and errors rejects the promise with an error carrying the AppleScript error number as its errorNumber property.
Parameters
- source: string
  The AppleScript source text.
- Optional options: AppleScriptOptions
  See AppleScriptOptions.
Returns Promise<AppleScriptResult>
A promise for the script's return value — see AppleScriptResult.
Example
```
const script = `
on addReminder(theName)
  tell application id "com.apple.reminders"
    make new reminder with properties {name:theName}
  end tell
end addReminder`;
await popclip.runAppleScript(script, {
  handler: "addReminder",
  parameters: [popclip.input.text],
  permissions: ["reminders"],
});
```
- Defined in popclip.d.ts:1209

runAppleScriptFile

runAppleScriptFile(path, options?): Promise<AppleScriptResult>
Run an AppleScript from a file in the extension package.

The same as runAppleScript() in every way except where the script comes from: path names a script file inside the package, relative to the package root. An .applescript file is read as source text; an .scpt (compiled script) file is opened by the script runner directly. Other file types, and paths outside the package, are refused.
Parameters
- path: string
  Package-relative path of the .applescript or .scpt file.
- Optional options: AppleScriptOptions
  See AppleScriptOptions.
Returns Promise<AppleScriptResult>
A promise for the script's return value — see AppleScriptResult.
Example
```
const result = await popclip.runAppleScriptFile("scripts/lookup.applescript", {
  handler: "lookup",
  parameters: [popclip.input.text],
});
```
- Defined in popclip.d.ts:1235

runShortcut

runShortcut(name, options?): Promise<AppleScriptResult>
Run a shortcut from the user's Shortcuts library, by name.

May only be called during the action phase.

Bad input (a missing name, a non-string input) throws immediately, and nothing runs. A shortcut that could not be run, or that errors, rejects the promise.
Parameters
- name: string
  The name of the shortcut, exactly as it appears in the Shortcuts app.
- Optional options: {
  input?: string;
  }
  input: text passed to the shortcut as its input; omitted means none.
  - Optional input?: string
Returns Promise<AppleScriptResult>
A promise for the shortcut's result — see AppleScriptResult. The result is the shortcut's output: what its last action produces, or what it passes to a "Stop and Output" action. A shortcut that produces no output resolves to undefined.
Example
```
const result = await popclip.runShortcut("My Shortcut", { input: popclip.input.text });
```
- Defined in popclip.d.ts:1259

settingsRequiredError

settingsRequiredError(message?): Error
Returns an Error to throw to send the user to the settings UI without clearing the sign-in (for example a required option is missing or invalid).
Parameters
- Optional message: string
  Optional message for logs/diagnostics.
Returns Error
- Defined in popclip.d.ts:1090

share(serviceName, items): Promise<void>
Share items with a named macOS sharing service.
Parameters
- serviceName: string
  The name of the sharing service to use.
- items: (string | UrlObject | RichString)[]
  An array of items to share. Each item can be a string, a RichString object, or a UrlObject.
Returns Promise<void>
Example
```
// share a string with the Messages service
popclip.share("com.apple.share.Messages.window", ["Hello, world!"]);
// share a URL with the Safari Reading List service
popclip.share("com.apple.share.System.add-to-safari-reading-list", [{ url: "https://example.com" }]);
// share a an html string with the Notes service
const item = new RichString("Some <b>simple</b> html", { format: html })
popclip.share("com.apple.Notes.SharingExtension", [item]);
```
The list of available sharing services is determined by the user's system configuration.

Returns a promise that resolves when the share completes (or when the user cancels the share UI), and rejects if macOS reports that the share failed. The share UI can stay open indefinitely, so only await this if your action needs to wait for the outcome.

Throws
If the service name is not recognized, or if the service cannot handle the supplied items, an error is thrown.
- Defined in popclip.d.ts:1426

showFailure

showFailure(): void
PopClip will show an "X" symbol to indicate failure.

Returns void
- Defined in popclip.d.ts:1063

showSettings

showSettings(): void
PopClip will open the settings UI for this extension.

If the extension has no settings, this method does nothing.

Returns void
- Defined in popclip.d.ts:1070

showSuccess

showSuccess(): void
PopClip will show a checkmark symbol to indicate success.

Returns void
- Defined in popclip.d.ts:1058

showText

showText(text, options?): void
Display text to the user.
Parameters
- text: string
  The text to display.
- Optional options: {
  preview?: boolean;
  style?: "compact" | "large";
  }
  Options.
  - Optional preview?: boolean
    Applies to compact display mode only. If true, and the app's Paste command is available, the displayed text will be in a clickable button, which clicked, pastes the full text.
  - Optional style?: "compact" | "large"
    Display style:
    
    compact (default): Show the text inside PopClip's popup. It will be truncated to 160 characters when shown.
    
    large: Show as "Large Type" in full screen.
Returns void
- Defined in popclip.d.ts:1038

signInRequiredError

signInRequiredError(message?): Error
Returns an Error to throw when the stored sign-in credential is no longer valid (for example the server rejected or revoked the token). PopClip clears the saved secret — so the extension appears signed out — and opens the settings UI to sign in again.
Parameters
- Optional message: string
  Optional message for logs/diagnostics.
Returns Error
Example
```
if (isAuthError(e)) throw popclip.signInRequiredError();
```
- Defined in popclip.d.ts:1082

Interface PopClip

Index

Properties

Methods

Properties

Readonly context

Readonly input

Readonly modifiers

Readonly options

Methods

appear

Returns void

copyContent

Parameters

Returns Promise<void>

copyText

Parameters

Returns Promise<void>

openTemplateUrl

Parameters

Optional activate?: boolean

Optional app?: string

Optional backgroundTab?: boolean

Optional clean?: boolean

Optional copy?: boolean

Optional options?: { [key: string]: string; }

[key: string]: string

Optional plus?: boolean

Optional verbatim?: boolean

Returns Promise<void>

Example

openUrl

Parameters

Optional activate?: boolean

Optional app?: string

Optional backgroundTab?: boolean

Returns Promise<void>

Example

pasteContent

Parameters

Returns Promise<void>

pasteText

Parameters

Returns Promise<void>

Example

performCommand

Parameters

Optional transform?: "none" | "plain"

Returns Promise<void>

Example

pressKey

Parameters

Optional target?: "session" | "app" | "hid"

Returns Promise<void>

Examples

pressKeys

Parameters

Optional target?: "session" | "app" | "hid"

Returns Promise<void>

revealFile

Parameters

Returns void

Example

runAppleScript

Parameters

Returns Promise<AppleScriptResult>

Example

runAppleScriptFile

Parameters

Returns Promise<AppleScriptResult>

Example

runShortcut

Parameters

Optional input?: string

Returns Promise<AppleScriptResult>

Example

settingsRequiredError

Parameters

Returns Error

share

`Readonly` context

`Readonly` input

`Readonly` modifiers

`Readonly` options

`Optional` activate?: boolean

`Optional` app?: string

`Optional` backgroundTab?: boolean

`Optional` clean?: boolean

`Optional` copy?: boolean

`Optional` options?: {
[key: string]: string;
}

`Optional` plus?: boolean

`Optional` verbatim?: boolean

`Optional` activate?: boolean

`Optional` app?: string

`Optional` backgroundTab?: boolean

`Optional` transform?: "none" | "plain"

`Optional` target?: "session" | "app" | "hid"

`Optional` target?: "session" | "app" | "hid"

`Optional` input?: string

`Optional` preview?: boolean

`Optional` style?: "compact" | "large"