CLI & MCP
Use Toolbox from a terminal or an AI assistant.
Toolbox includes a command-line interface (CLI) and an MCP server. Use the CLI in your terminal or scripts. MCP (Model Context Protocol) lets an AI assistant find and run the tools. Both work without opening an app window.
Set up the command
Install Toolbox first. You can run it using the full executable path shown above, or set up the toolbox shortcut used in these examples. On macOS, run the command here to create that shortcut. Run the executable directly rather than using the macOS open command, which won’t return results to your terminal.
sudo ln -s "/Applications/Toolbox.app/Contents/MacOS/Toolbox" /usr/local/bin/toolbox
The command line
Choose a tool, add your inputs and options, and set an output folder. Running toolbox without arguments opens the app. The CLI and MCP support all four tools and the same export settings, including print colors, settings for individual logo variations, and custom font roles.
toolbox help # show tools and usage toolbox convert --help # show Convert options toolbox lockup logo.svg --print none --padding 0.1 --out . toolbox palette '#D32F05' '#003A5D' --name Acme --out . toolbox specimen --template classic --family Helvetica --out . toolbox convert a.heic b.png --formats webp --compression 40 --out ~/Desktop
- Arguments
- Pass file paths directly to convert and lockup, or hex colors to palette. You don’t need a flag for these inputs.
- Paths
- Relative paths start from your current folder. Use ~ for your home folder, and quote paths that contain spaces.
- Lists
- Separate values with spaces or commas: --formats webp png or --formats=webp,png. To skip an output group, use none, as in --print none.
- Switches
- Use --social to include profile images and --no-social to leave them out.
- JSON
- Add --json to a tool command to receive the result as JSON.
- Output
- Use --out for exports and previews. Toolbox creates a new folder inside that destination, leaving existing files untouched. Inspecting files, listing fonts, and reading library records don’t need an output folder.
- Exit codes
- 0 means success, 1 means the job failed, and 2 means the command is invalid. Normal CLI results go to stdout; errors go to stderr.
Print colors & type
You can assign print colors, adjust individual logo variations, name swatches, sample images, and define font roles. These options are available from version 1.1.0. Use inspect to find the colors in your artwork and fonts to list installed font families and styles.
Structured flags such as --palette and --roles take a quoted JSON array. Use the detected sourceHex from your artwork and font names installed on your computer. CMYK values are percentages from 0 to 100. MCP accepts the same arrays directly, without shell quoting.
toolbox lockup logo.svg --action inspect --json
toolbox lockup logo.svg --name Acme --out ./exports --palette '[{"sourceHex":"#D32F05","cmyk":[0,78,98,17],"pantone":"1665 C"}]'
toolbox specimen --action fonts --json
toolbox specimen --title "Acme type" --out ./exports --roles '[{"label":"Heading","family":"Helvetica","face":"Bold","size":40}]'Preview & saved work
Use --action inspect to check settings and see which files will be exported. It doesn’t write any files. Convert also reports output sizes, and Palette returns a preview of the generated code. To save previews you can open, use --action preview with --out.
Add --save when exporting to keep the settings in the app’s library. The result includes a savedID; use that value in place of RECORD_ID to reopen the work. Any options you pass with the new command override the saved settings.
Use library-get to read a saved record and library-remove to delete its library entry. Removing an entry leaves the exported files in place.
toolbox lockup logo.svg --print none --save --out ./exports --json toolbox lockup --action library-list --json toolbox lockup --saved RECORD_ID --action inspect --json toolbox lockup --saved RECORD_ID --padding 0.15 --save --out ./exports --json
Options
The tables below list supported flags and defaults. To check your installed version, run toolbox <tool> --help. Use toolbox list to get the option schemas as JSON.
List
Run toolbox list for a JSON catalog of all four tools, with descriptions, argument schemas, and examples. Use toolbox describe followed by a tool name for a single tool.
toolbox list # every tool, as JSON toolbox describe convert # one tool, as JSON
Run
Pass the tool name and arguments to --run as a JSON object. Toolbox returns the output folder, file names, and any warnings. Successful jobs exit with code 0; failed jobs exit with code 1 and an error message. Replace the example paths with your own and adjust the macOS paths and shell quoting for your system.
toolbox --run '{"tool":"convert","args":{
"input":["/Users/me/Pictures/IMG_0001.heic"],
"formats":["webp"],
"compression":40,
"longestEdge":2000,
"out":"/Users/me/Desktop"
}}'{
"ok": true,
"tool": "convert",
"outputDir": "/Users/me/Desktop/Converted",
"files": ["IMG_0001.webp"],
"warnings": []
}{
"ok": false,
"tool": "convert",
"error": "Could not read /Users/me/Pictures/IMG_0001.heic"
}Serve
To connect an AI assistant, add the server configuration shown here to its MCP settings. Use the executable path for your platform. The --mcp flag starts Toolbox’s server over standard input and output. Claude Code reads project settings from .mcp.json. Protocol messages go to stdout and logs go to stderr.
Once connected, ask your assistant to convert screenshots to WebP, package logo SVGs, or extract colors from artwork. Include the source files and destination folder in your request.
toolbox --mcp
{
"mcpServers": {
"toolbox": {
"command": "/Applications/Toolbox.app/Contents/MacOS/Toolbox",
"args": ["--mcp"]
}
}
}