CLI Reference

Global Options

icons [command] [options]

Help

icons --help
icons -h

Version

icons --version
icons -V

Commands

`init`

Initialize an icons.json configuration file in your project root.

icons init

Interactive prompts:

Output directory for generated icons
Default icon set (e.g., lucide, heroicons, tabler)
Default icon size

Generated file:

{
  "$schema": "https://saas-js.dev/icons/schema.json",
  "outputDir": "/src/components/icons",
  "defaultIconSet": "lucide",
  "iconSize": "1em",
  "aliases": {}
}

`add`

Add icons to your project by generating React components.

icons add [options] <icon-names...>

Arguments:

<icon-names...> - One or more icon names to add

Options:

-s, --set <icon-set> - Icon set to use (optional if defaultIconSet is configured)
-o, --outdir <path> - Output directory for generated icons

Examples:

# Basic usage with explicit icon set
icons add --set lucide home user settings

# Using short flag
icons add -s heroicons home user settings

# Using default icon set (if configured in icons.json)
icons add home user settings

# Custom output directory
icons add --set lucide --outdir ./src/icons home user

# Short flags
icons add -s lucide -o ./src/icons home user

# Add multiple icons at once
icons add --set lucide home user settings mail search edit trash plus minus

`mcp`

Start the MCP (Model Context Protocol) server for AI-assisted icon management.

icons mcp

This starts a server that can be used by AI assistants to help manage your icons. The MCP server provides:

Icon search capabilities
Automated icon addition
Configuration management
Icon set browsing

Exit Codes

0 - Success
1 - General error
2 - Configuration error
3 - Network error
4 - File system error

Common Usage Patterns

Project Setup

# Initialize new project
icons init

# Add common icons
icons add --set lucide home user settings mail search

Feature-based Icon Addition

# Authentication icons
icons add --set lucide log-in log-out user-plus user-minus

# Navigation icons
icons add --set lucide home dashboard settings help

# Action icons
icons add --set lucide plus minus edit trash save

Working with Multiple Icon Sets

# Lucide icons for general UI
icons add --set lucide home user settings

# Heroicons for specific components
icons add --set heroicons academic-cap beaker

# Font Awesome for brand icons
icons add --set fa-brands github twitter linkedin

Error Handling

Common Errors

Configuration not found:

Error: No icons.json configuration found. Run 'icons init' first.

Invalid icon set:

Error: Icon set 'invalid-set' not found. 
Available sets: lucide, heroicons, tabler, feather, etc.

Icon not found:

Error: Icon 'invalid-icon' not found in set 'lucide'.
Try browsing available icons at https://icon-sets.iconify.design/lucide

Network error:

Error: Failed to fetch icon data. Check your internet connection.

File system error:

Error: Cannot write to output directory '/src/components/icons'.
Check permissions and ensure the directory exists.

Debugging

Enable verbose output for debugging:

DEBUG=icons:* icons add --set lucide home user

Tips and Best Practices

1. Use Consistent Icon Sets

# Good: Stick to one primary icon set
icons add --set lucide home user settings mail

# Avoid: Mixing different styles
icons add --set lucide home
icons add --set heroicons user  # Different style

2. Batch Icon Addition

# Good: Add related icons together
icons add --set lucide home user settings mail search edit trash plus minus

# Less efficient: Add icons one by one
icons add --set lucide home
icons add --set lucide user
icons add --set lucide settings

3. Use Aliases for Better Names

Set up aliases in your icons.json:

{
  "aliases": {
    "house": "home",
    "cog": "settings",
    "envelope": "mail"
  }
}

Then use the original names:

icons add house cog envelope

4. Organize Output Directory

# Feature-based organization
icons add --set lucide --outdir ./src/icons/navigation home dashboard
icons add --set lucide --outdir ./src/icons/actions plus minus edit trash

5. Check Icon Availability

Before adding icons, check if they exist:

Visit Iconify Icon Sets
Browse your chosen icon set
Copy the exact icon names

Integration with Build Tools

Next.js

# Add to Next.js project
icons init
# Configure outputDir: "./components/icons"
icons add --set lucide home user settings

Vite

# Add to Vite project
icons init
# Configure outputDir: "./src/components/icons"
icons add --set lucide home user settings

Create React App

# Add to CRA project
icons init
# Configure outputDir: "./src/components/icons"
icons add --set lucide home user settings

Continuous Integration

GitHub Actions

name: Update Icons
on:
  push:
    paths:
      - 'icons.json'

jobs:
  update-icons:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm install -g @saas-js/iconify
      - run: icons add --set lucide home user settings
      - name: Commit changes
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add .
          git commit -m "Update icons" || exit 0
          git push

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

# Check if icons.json was modified
if git diff --cached --name-only | grep -q "icons.json"; then
  echo "Icons configuration changed, updating icons..."
  icons add --set lucide home user settings
  git add src/components/icons/
fi

Next Steps

Configuration - Detailed configuration options
Icon Sets - Browse available icon sets
TypeScript - TypeScript integration

CLI Reference

On this page