PICO-8 Wiki


While there are a lot of tools available within IDEs that make it easier to run a PICO-8 Cartridge directly from the development platform, there isn’t many instructions on the interwebs to make PICO-8 just be more friendly to MacOS in General:

Here is how you create a Quick Action, in MacOS Finder, to start PICO-8 Cartridges


  • I use a Macbook 12”, the model without the fans. When running Visual Studio Code, i can reach average core temps of up to 197-205 degrees. When you are writing lua, that’s just silly overhead.
  • Sublime Text is nice, but I prefer BBEdit with its instant formatting tools.
  • I’m running Bitbucket, and Sourcetree to run a git repo, so i definitely want to host my dev files separately from the default folder.
  • Changing the default config file to point to my dev folder is all good and well, but i still have to change the folder and then run the file.


  • I want to run a PICO-8 cart directly from the Finder using a Quick Action

Action Steps[]

Add Automator and PICO-8 to Input Monitoring[]

You must add the ability for PICO-8 and Automator to monitor inputs in the Operating system

  • Go to System Preferences from your MacOS
  • Select the Security & Privacy Option
  • Go to the Privacy tab at the top of the Menu
  • Select the lock in the bottom left hand corner to allow for edits to be made. Please Note: You must have root access to this Mac
MacOS - Elevate Permissions in Security and Privacy
  • After you Authenticate, select Input Monitoring from the Side Menu
  • Drag the Icons for Automator and PICO-8 from your Finder->Applications Window into the Input Monitoring Window
MacOS - Drag App to Security and Privacy Tab
  • Make sure the the Check box is enabled next to the Dragged Application
  • You have now activated Input Monitoring for PICO and Automator

Create Workflow in Automator[]

Now we will create the proper steps to make a Quick Action in the MacOS.

While creating a workflow in Automator usually adds the Quick Action automatically to Finder, I have found this to be not true in the latest version of the OS (Catalina 10.15). I have added the extra steps at the end to help those who do not automatically see this added in their OS.

  • Open Automator from the Applications Menu in Finder (Or using Spotlight)
  • Select New from the Menu
  • Select Quick Action from the Choose a type for your Document menu. Confirm by selecting Choose
MacOS - Automator - Quick Action Selection
  • Enter the Following Information in the Next Section:
    • Workflow Receives Current = files and folders
    • in = Finder
    • Color = your preference
    • Image = Choose..
  • From the Actions side menu, type “script” in the Search Bar. Drag the option Run Shell Script to the workspace
    MacOS - Automator - Shell Script Action Drag
  • From within the Run Shell Script dialog, use the following values:
    • Shell = Bash, zsh, and many others will suffice.
    • Pass Input = as arguments
    • Script = this command:
/Applications/PICO-8.app/Contents/MacOS/pico8 -run $*
  • Verify that you see the same information in your screen
MacOS - Automator - Shell Script for PICO-8
  • From Automator, select File - Save
  • Name your File What ever Nomenclature you like. I chose Open Cart in PICO-8

From Here, you should be able to see a new Quick Action Item Available from the Finder

MacOS - Finder - New Quick Action for PICO-8

Test Workflow in Automator (Optional)[]

If you want to run your workflow in Automator to make sure the process works, you simply need to pass a value to the Script Function

Automator with Testing Overlay
  • From the Actions Sidebar Menu, Type “Get Specified Text” in Search
  • Drag Get Specified Text into the Workspace above the Shell Script Function
  • Enter the path of a known cart on your machine. An example would be:
/Users/MyMacUser/Library/Application Support/pico-8/carts/arkanoid.p8
  • Select the Run button at the top of the window
  • You should see PICO-8 the game you have referenced

Where is my Quick Action?!?

I had the same issue...

Follow these next steps to ensure you can see the Quick Action in Finder. I found this was the way i need to follow for MacOS Catalina 10.15

Export from Automator[]

  • From Automator, select File - Export
  • Save File to Desktop. Name your File What ever Nomenclature you like. I chose Open Cart in PICO-8

Install Workflow to Quick Actions[]

MacOS - Finder - Install PICO-8 Quick Action
  • From Desktop, double click the file you just created. A dialog will appear
  • Select Install

From here, you should be able to see a new Quick Action Item Available from the Finder


PICO-8 Icon - github Request - Created by really-need-an-api-key


“Use Quick Action workflows on Mac” - Automator User Guide - https://support.apple.com/guide/automator/use-quick-action-workflows-aut73234890a/mac

“Open anything in VS Code using a MacOS quick action” - Written by Jim Bennett - https://www.jimbobbennett.io/open-anything-in-vs-code-using-a-macos-quick-action/

Visual Game Boy icon by Icons8


The TL;DR edition.

MacOS Quick Action - Open PICO-8 Cart

Use this file to create your own Quick Action on your machine. Might need some tweaking. Just use the instructions above in case you need assistance.

Prerequisite: You must perform the steps outlined in the Add Automator and PICO-8 to Input Monitoring section in order to properly use this Quick Action.