DOCSEARCHbyAlgolia
Submit Docs

Platypus

repository·master·Indexed 25 days ago

https://github.com/sveinbjornt/platypus

A macOS developer tool that wraps command-line scripts (Shell, Python, Ruby, etc.) into native application bundles. It provides various graphical interfaces—including Progress Bar, Text Window, Web View, Status Menu, and Droplet—to help developers share automation tools with non-technical users. Platypus supports a wide range of interpreters, root privilege execution via the macOS Security Framework, and a command-line tool for CI/CD integration.

Tokens
4.7K
Snippets
6
Records
34
Agent score
86%

What's inside Platypus

  1. Overview of Platypus

    master
    Platypus is a developer tool for macOS that creates native application wrappers around scripts. It transforms scripts into regular .app bundles that can be launched from the Finder or Dock without using a command-line interface. The generated applications use a special executable binary that runs the script and captures its output, which can then be displayed via progress bars, text views, Status Item menus, or WebKit-based web views.

  2. Built-in Platypus Examples

    master

    Platypus includes several built-in examples accessible via the Examples submenu in the Profiles menu. These demonstrate various capabilities:

    • AdminPrivilegesDemo: Running scripts with root privileges.
    • AlertMe: Using ALERT: and PROGRESS: syntax.
    • DataURLifier: Converting dropped files to Data URIs.
    • FastDMGMounter: Quick .dmg mounting using hdiutil.
    • IcnsToIconset: Converting .icns to .iconset folders.
    • ImageResizer: Using sips to resize images.
    • MacbethMenu: Interactive status menu with speech synthesis.
    • PostToNotificationCenter: Using NOTIFICATION: syntax.
    • ProcessMenu: Status menu displaying ps cax output.
    • ProgressBar: Controlling progress bar via script output.
    • SayURLSchemeHandler: Handling custom say:// URI schemes.
    • SpeakDroplet: Reading text files via speech synthesizer.
    • SpotlightInfo: Viewing Spotlight metadata of dropped files.
    • StatusMenuDemo: Setting menu icons and submenus.
    • SysLoadMenu: Status menu displaying w output.
    • TarGzipper: Creating gzipped tar archives from dropped files.
    • WordCountService: Service app that counts words and shows an alert.

  3. Configure the Script Interpreter and Arguments

    master

    Use the Script Type setting to specify which interpreter should run your script. You can select a predefined language from the menu or provide a manual path to an interpreter binary. Platypus attempts to auto-detect the type using the file suffix or the shebang line (#!).

    Use the Args field to add specific arguments to the script or its interpreter.

  5. Install the Platypus command line tool in CI environments

    master

    To use Platypus for automation or within a CI/CD pipeline, you can install the command line tool binary to /usr/local/bin/platypus using the following steps:

    curl -L -O https://github.com/sveinbjornt/Platypus/releases/download/v5.5.0/platypus5.5.0.zip
unzip -q platypus5.5.0.zip
cd Platypus.app/Contents/Resources
sudo bash InstallCommandLineTool.sh

  6. Use Profiles to save and load Platypus configurations

    master

    Profiles allow you to save your Platypus application configuration settings. These can be reused via the Platypus GUI or the platypus command line tool for automation. Profiles are stored as .platypus files (standard macOS XML property lists) in ~/Library/Application Support/Platypus/Profiles.

    • To load a profile in the GUI: Select it from the Profiles menu.
    • To reveal a profile in Finder: Hold the Command key while selecting the profile from the menu.
    • To edit manually: Use a plain text editor or Xcode. Note that while Platypus 5.2+ resolves relative paths in Profiles, the app/CLI does not generate them; you must edit them manually if you want relative paths.
    /usr/local/bin/platypus -P myProfile.platypus MyApp.app

  7. Configure File Dropping and URI Handling

    master

    Extend your application's ability to receive input through these settings:

    • Accept dropped items: Enables the app to accept dragged files or text snippets.
      • Drop Settings: Use UTIs (e.g., public.folder) or filename suffixes to restrict accepted types. Dropped file paths are passed as arguments to the script.
      • Accept Dropped Text: Dragged text is passed to the script via stdin.
    • Provide macOS Service: Registers the app as a Dynamic Service in the macOS Services menu.
    • Register as URI scheme handler: Registers the app to handle custom URI schemes (e.g., myscheme://). When a matching URL is opened, the URL is passed to the script as an argument.

  8. Install Platypus

    master
    Download the Platypus application bundle to create native Mac apps from your scripts. The current version (v5.5.0) is a Universal ARM/Intel 64-bit app compatible with macOS 11 or later. It is Developer ID signed and notarized.

  9. Select a User Interface Type

    master

    Platypus provides six interface modes to control how your application interacts with the user:

    • None: A windowless application. All script output is redirected to stderr.
    • Progress Bar: Displays a window with an indeterminate progress bar and a "Cancel" button. Script output is shown line-by-line above the bar. Use the "Show details" button to see full output.
    • Text Window: Displays a window containing script output. Note: This is not an interactive terminal; it does not support stdin prompts, standard terminal commands, or ncurses interfaces.
    • Web View: Renders script output as HTML in a WebView. You can include images or support files by adding them to Bundled Files and referencing them relatively.
    • Status Menu: Creates a macOS menu bar item. Clicking the item executes the script and shows output in a menu. Selecting a menu item re-runs the script with that item's title passed as an argument.
    • Droplet: Provides a window for users to drag and drop files onto for processing. Displays output and a circular progress indicator during execution.

  10. Customize the application window and localization

    master

    Platypus applications do not support native localization or custom window dimensions by default. To enable these:

    1. When creating the app, uncheck the "Optimize Application (strip nib file)" option.
    2. The resulting MainMenu.nib file (located at Contents/Resources/MainMenu.nib inside the bundle) can then be edited using Xcode to change dimensions or add localizations.
    3. To reuse a custom UI, add your modified .nib file to the Bundled Files list during creation to overwrite the default.
    4. Alternatively, if using the Platypus CLI, use the -H flag to specify an alternate nib file.

  12. Access bundled files and application paths in scripts

    master

    When a Platypus-generated application runs, the script executes from the Resources directory of the application bundle (e.g., MyApp.app/Contents/Resources).

    • Bundled Files: Any files added to the 'Bundled Files' list in Platypus are available in the script's current working directory.
    • Application Bundle Path: To access the root of the application bundle, use ../.. relative to the script.
    • Container Directory: To access the directory containing the application bundle, use ../../...