SF Symbols from the Command Line and AI Agents

SF Symbols 27 ships a command-line tool. Apple mentions it in the What's New window, next to a Copy path button, and pitches it for scripts and AI agents:

It has two commands, search and export, and they cover more than looking up names. You can check a symbol against your deployment target, catch renames, and render PNGs without opening the app.

Setting up #

The binary lives inside the app bundle:

The path is long and has a space in it, so add an alias to your shell config:

A symlink won't work. The tool looks for SF Symbols.app relative to its own path, so a link in /usr/local/bin fails to find its resources.

The rest of the post uses plain sfsymbols. sfsymbols help search and sfsymbols help export list every option.

Searching #

A bare query searches the whole catalog. Two flags make the output more useful:

--show-glyph adds the symbol itself as the first column. It renders in Terminal on macOS, which falls back to SF Pro, but not in most editors.

Match styles

The default style, permissive, matches name components, aliases, tags, and lemmas, the same way the app's search does. That's why weather starts with winter sports:

--match-style switches to two stricter styles that only look at names:

• nameContains :car.fill matchescar.fill andcablecar.fill .
• exactName :car.fill matches onlycar.fill .

Categories

--category-filter takes the same categories as the app's sidebar. A plain bolt search starts with the bolt itself, while the weather category turns it into thunderstorms:

An unknown key prints the full list, so --category-filter help is the fastest way to see them. My favorite is whatsnew, which answers "what did Apple add this year?":

Reverse lookup

Search works on code points too:

You can also paste the glyph itself, for example one copied from a Figma file, and get the name back.

Checking your deployment target #

--min-platform takes your deployment target, written as a platform and version with no space, like iOS16, and keeps only symbols available on that version. Repeat it for multiplatform apps, and a symbol has to pass every one. Without the filter, sun.max matches seven symbols:

An app targeting iOS 15 and macOS 12 gets four of them:

The filter knows about renames. xmark.bin exists on iOS 13, but under a different name:

If your app supports iOS 13, bin.xmark is the name that works there.

Rendering modes

A symbol's availability isn't one number. --json splits it by rendering mode:

heart.fill is on iOS 13, but multicolor rendering needs iOS 15. The plain text output only shows monochrome availability.

Exporting #

export renders a symbol to PNG or PDF with the same options as the app's

export panel: --point-size is a font size, not a canvas size. The file above is 198 × 198 pixels: the glyph's own bounds at 64 points, times three.

For several formats at once, use --output-dir instead of --output. Files are named after the symbol:

SVG, the default format, isn't an icon. It's the editable design template the app produces, with all weights, scales, and annotations on a 3300 × 2200 canvas. Use it as a starting point for a custom symbol. Rendering options don't apply to it.

Letting agents verify symbols #

Agents are good at picking plausible symbol names and bad at knowing whether they exist. checkmark.circle.badge looks real, but the catalog doesn't have it:

A few lines in CLAUDE.md or AGENTS.md make the agent check before it writes code:

Now the agent searches, verifies, and only then writes Image(systemName:). It can also run export to show you the candidates before touching the views.