CLI & MCP
Use Toolbox from a terminal or an AI assistant.
The installed app includes a command-line interface (CLI) for scripts and an MCP server for AI assistants. MCP, the Model Context Protocol, lets an assistant discover and run the tools. Both use the app’s export engine without showing a window.
Set up the command
Install Toolbox first. The paths above show where to find its executable. The examples below use toolbox as the command; you can substitute the full path. On macOS, the link shown here makes that shortcut available from your terminal. Run the executable directly: the macOS open command detaches it, so you won’t see the results in your terminal.
sudo ln -s "/Applications/Toolbox.app/Contents/MacOS/Toolbox" /usr/local/bin/toolbox
The command line
Choose a tool, supply its inputs and options, and set an output folder. Running toolbox with no arguments opens the desktop app. All four tools support the same export settings through the app, CLI, and MCP, including print colors, per-variation settings, 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
- Values without a flag become the main input: file paths for convert and lockup, hex colors for palette.
- 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
- Export and preview require --out. Toolbox creates a new subfolder inside that destination and leaves existing files in place. Inspection, font discovery, and library queries need no destination.
- 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
New in 1.1.0: assign print colors, set options for individual logo variations, name palette swatches, sample images, and define your own font roles. Use inspect to find source colors and fonts to list installed families and faces.
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 see settings and planned files without writing anything. Convert also measures output sizes; Palette returns previews of its generated code. Use --action preview with --out to write previews you can open.
Add --save to an export to make it available in the app’s library. The result includes a savedID. Replace RECORD_ID in these examples with that value to reopen the work. Explicit options override 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
The options
Supported flags and their defaults are listed below. Run toolbox <tool> --help for the options in your installed version, or toolbox list for their JSON schemas.
List
Run toolbox list to get the full tool catalog as JSON, including descriptions, argument schemas, and examples. Use toolbox describe followed by a tool name to inspect just that tool.
toolbox list # every tool, as JSON toolbox describe convert # one tool, as JSON
Run
Pass a JSON object with the tool name and its arguments to --run. Toolbox checks the arguments, runs the job, and returns JSON with the output folder, file names, and warnings. A successful job exits with code 0. A failed job exits with code 1 and includes an error message. Replace the example paths with your own. The examples use macOS paths and shell quoting; adjust both 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
Start Toolbox with --mcp to expose the four tools to an MCP client over standard input and output. Add the example server configuration to your client’s MCP settings, using the executable path for your platform. For Claude Code, the project configuration file is .mcp.json. Protocol messages use stdout; logs use 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"]
}
}
}