Command Line Interface

The Bobcorn CLI lets you manage icon font projects entirely from the terminal. Install it from the Settings panel inside the Bobcorn app — click the Install button in the "Command Line Interface" section.

After installation, open a new terminal and verify:

bobcorn --version

The CLI automatically detects .icp project files in the current directory. You can also specify a path explicitly. The resolution priority is:

1. Explicit path argument — passed directly to the command
2. --project flag — global option for all commands
3. Auto-discover — scans the current directory for a .icp file

# 1. Explicit path argument
bobcorn project inspect my-icons.icp

# 2. Global --project flag
bobcorn --project my-icons.icp icon list

# 3. Auto-discover (run from the directory containing the .icp file)
cd my-project/
bobcorn icon list

By default the CLI outputs human-readable text. Add --json for structured JSON output, ideal for scripting and AI-agent integration.

JSON Envelope Structure

Every JSON response follows a consistent envelope:

{
  "ok": true,
  "data": { ... },
  "meta": {
    "command": "icon list",
    "projectPath": "/path/to/project.icp",
    "duration_ms": 42,
    "version": "1.0.0"
  }
}

Three Response States

Create, inspect, and configure .icp project files.

# Create a new empty project
bobcorn project create my-icons.icp --name "App Icons"

# Inspect project metadata (name, prefix, icon/group counts)
bobcorn project inspect

# Set the project name (also sets the font prefix)
bobcorn project set-name "New Name"

# Set font prefix (alias for set-name)
bobcorn project set-prefix "MyIcons"

# Save a copy of the project to a new file
bobcorn project save-as backup.icp

Import, list, rename, move, copy, delete, and configure icons. All icon references use UUID — use icon list --json to discover IDs.

# Import SVG files (auto-assigned UUID and unicode code)
bobcorn icon import *.svg --group Navigation

# List all icons (table format)
bobcorn icon list

# List icons in a group as JSON
bobcorn icon list --group Navigation --json

# Rename an icon
bobcorn icon rename <id> new-name

# Move icons to a different group
bobcorn icon move <id1> <id2> --to "Other Group"

# Copy icons to another group (new UUIDs assigned)
bobcorn icon copy <id> --to "Backup"

# Delete icons (soft-delete, moved to recycle group)
bobcorn icon delete <id>

# Set Unicode code point (hex, PUA range E000-F8FF)
bobcorn icon set-code <id> E100

# Replace icon SVG content with a new file
bobcorn icon replace <id> new-icon.svg

# Export individual icons as SVG files
bobcorn icon export-svg <id> --out ./exports

# Mark/unmark icon as favorite
bobcorn icon set-favorite <id>
bobcorn icon set-favorite <id> --off

# Replace a color in icon SVG content
bobcorn icon set-color <id> --from "#000" --to "#333"

# Output raw SVG content to stdout
bobcorn icon get-content <id>

Organize icons into named groups. Groups control display order in the sidebar and can be used to filter exports.

# List all groups
bobcorn group list

# Create a new group
bobcorn group add "New Category"

# Rename an existing group
bobcorn group rename "Old Name" "New Name"

# Delete a group (icons moved to uncategorized)
bobcorn group delete "Empty Group"

# Set display order (list groups in desired order)
bobcorn group reorder Navigation Actions Settings

# Set group description (shown in sidebar)
bobcorn group set-description Navigation "Main nav icons"

# Move icons into a group (alternative to icon move)
bobcorn group move-icons Navigation <id1> <id2>

Generate font files and export SVGs. Font export supports SVG, TTF, WOFF, WOFF2, and EOT formats with optional CSS and JS companion files.

# Export font with specific formats
bobcorn export font --out ./dist --formats woff2,ttf

# Export font with custom name and companion files
bobcorn export font --out ./dist --font-name "MyIcons" --css --js

# Export all icons as individual SVG files
bobcorn export svg --out ./svg-icons

# Export only icons from a specific group
bobcorn export svg --out ./svg-icons --group Navigation

Find icons by name and manage bookmarked favorites.

# Search icons by name
bobcorn search "arrow"

# Search within a group with result limit
bobcorn search "home" --group Navigation --limit 10

# List all favorite icons
bobcorn favorite list

Manage icon weight and scale variants (SF Symbols style). Variant generation requires the Bobcorn GUI, but you can list and delete variants from the CLI.

# List all variants of an icon
bobcorn variant list <id>

# Delete all variants of an icon (base icon preserved)
bobcorn variant delete <id>

The Bobcorn CLI is designed to work seamlessly with AI coding agents such as Claude Code, Codex, Cursor, and others. Use --json for structured output that agents can parse reliably.

Key Principles

• Every command supports --json for machine-readable output
• The JSON envelope is consistent across all commands — agents can rely on the ok / error / data structure
• Project auto-discovery means agents can simply cd into a project directory and run commands without specifying file paths
• Error codes are predictable: ICON_NOT_FOUND, GROUP_NOT_FOUND, FILE_IO_ERROR, etc.

Agent Workflow Example

# Agent creates a project
bobcorn project create app-icons.icp --name "MyApp" --json

# Agent imports SVGs
bobcorn icon import ./design/*.svg --json

# Agent organizes into groups
bobcorn group add "Navigation" --json
bobcorn group add "Actions" --json

# Agent searches and moves icons
NAV_IDS=$(bobcorn search "nav" --json | jq -r '.data[].id')
bobcorn icon move $NAV_IDS --to "Navigation" --json

# Agent exports the font
bobcorn export font --out ./src/fonts --formats woff2 --json

Here is a full end-to-end bash script demonstrating a typical icon font workflow:

#!/bin/bash
set -e

# Create a new project
bobcorn project create my-app-icons.icp --name "MyApp"

# Import all SVG icons from the design directory
bobcorn icon import ./design/icons/*.svg

# Create groups to organize icons
bobcorn group add "Navigation"
bobcorn group add "Actions"
bobcorn group add "Status"

# Search for navigation icons and move them
NAV_ICONS=$(bobcorn search "nav" --json | jq -r '.data[].id')
for id in $NAV_ICONS; do
  bobcorn icon move "$id" --to "Navigation"
done

# Set group display order
bobcorn group reorder Navigation Actions Status

# Export font files for production
bobcorn export font --out ./src/fonts --formats woff2 --css

# Also export individual SVGs for documentation
bobcorn export svg --out ./docs/icons

echo "Done! Font files are in ./src/fonts"