Skip to content

Acorn’s Shell Tool

Acorn 8.6 includes a new shell tool which you can use to open images, diff images, run JavaScript, or start an MCP server.

Installing the Shell Tool

To install the shell tool, open choose the Acorn ▸ Settings… menu item and choose the Advanced tab.

Under the Automation section you will find a button titled “Install acorn Command Line Tool”. Click the button and you will be prompted to install the tool with an administrator password.

If the button instead says “View Install Instructions”, that means you’re running the App Store version of Acorn and should read the next section.

If You Got Acorn via the App Store

If you are using the App Store version of Acorn, you’ll need to do things a little differently because of App Store restrictions. Instead, you’ll need to open up the Terminal app (located in your /Applications/Utilities folder) and paste in the following line:

1
curl -fsSL https://flyingmeat.com/acorn/install-acorn-cli.sh | bash

Follow the instructions when prompted to to install the tool.

Using the 'acorn' Tool

Once installed, you can use the acorn tool from /usr/local/bin/acorn.

Running acorn -h will show you the various arguments you can give it.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
acorn [options...]
 -diff <file1> <file2>      Open up a diff window for the two image paths.
 -h                         Display this help information.
 -js, -javascript <file.js> Run the JavaScript code in the file for the given path.
 -jsa <file.js>             Activate Acorn and run the Javascript in the given file path.
 -jsio                      Run JavaScript code read from stdin.
 -mcp                       Run as a stdio MCP server exposing Acorn's JavaScript bridge.
 </path/to/image>           Open an image in Acorn with the given path.

In addition, a Skill for automating Acorn via JavaScript can be found at:
 Acorn.app/Contents/Resources/skills/acorn-javascript-api

Using the -diff argument with two images will open up Acorn’s image difference window, which allows you to compare the differences between two images.

The -js or -javascript arguments will read in a JavaScript file and send that to Acorn for automation.

The -jsa argument does the same as -js or -javascript, but will activate Acorn.

The -jsio argument will read JavaScript from stdin. For instance, if you wanted to quickly send a command to Acorn, you could use this argument to type in JavaScript and press control-d on a newline to end the input. Or you can use the echo command to have Acorn take a layered screenshot:

1
echo "acorn.takeLayeredScreenshot();" | acorn -jsio

MCP Server Instructions

If you would like to use the shell tool as an MCP server, you need to pass the -mcp argument to the tool. If your app or harness needs JSON instructions for using the tool, the following configuration is what you need:

1
2
3
4
5
6
7
8
{
  "mcpServers": {
      "acorn": {
          "command": "/usr/local/bin/acorn",
          "args": ["-mcp"]
      }
  }
}