docs / CLI Reference

CLI Reference

Commands

init

Create a new relaxicons.config.json interactively.

relaxicons init

Options:

• --framework <name>: Skip prompt and set framework.
• --force: Overwrite existing config.

add [icon-id]

Fetch an Iconify icon and generate a component. The icon id is optional when you pass --from.

relaxicons add lucide:alarm-clock

# Batch: comma list (bare names share the first prefix)
relaxicons add lucide:home,star,bell
# ...or fully-qualified per item
relaxicons add lucide:home,mdi:cog

# Batch from a file (one id per line or comma-separated)
relaxicons add --from icons.txt

Options:

• --framework <name>: Override config framework for this icon.
• --raw: Output raw optimized SVG (no component wrapping).
• --both: Also write cleaned SVG alongside component.
• --force: Overwrite an existing icon file.
• --from <file>: Read multiple icons from a file.
• --no-svgo: Disable SVGO optimization (if installed).

In batch mode, a missing icon or an existing file (without --force) is skipped and the rest of the batch still runs; the command exits non-zero (3 fetch, 4 duplicate) to signal partial failure.

collections

List available icon collection prefixes.

relaxicons collections
relaxicons collections --filter luc
relaxicons collections --json --limit 20

Options:

• --filter <text>: Filter collection prefixes.
• --limit <n>: Limit number printed.
• --json: Output JSON array.
• --fields <list>: Choose fields (name,title,count).

icons

List icons within a collection.

relaxicons icons lucide
relaxicons icons lucide --filter home
relaxicons icons lucide --json --limit 10

Options:

• --filter <text>: Filter icon names.
• --limit <n>: Limit number printed (default 50).
• --json: Output JSON array.

list (deprecated alias)

Alias for icons <collection>; deprecated and will be removed in v2.0. Use icons.

search

Search icons across all collections, or scope to one.

relaxicons search arrow
relaxicons search home --collection lucide
relaxicons search star --json --limit 20

Options:

• --collection <prefix>: Limit to a collection.
• --limit <n>: Maximum results to print.
• --json: Output JSON. Note: Results are fetched using cached collection metadata when available.

remove

Remove a generated icon file and update barrel exports.

relaxicons remove lucide:home

stats

Show icon counts per collection, or for one collection with -c.

relaxicons stats
relaxicons stats -c lucide --json

doctor

Validate Node version, config, and Iconify API reachability. Exits non-zero if any check fails (useful in CI).

relaxicons doctor
relaxicons doctor --verbose   # print environment details

migrate-config

Upgrade an existing relaxicons.config.json to the latest schema fields.

relaxicons migrate-config

regenerate

Regenerate icons from a manifest (CI helper). Each icon is generated in an isolated process, so --concurrency is safe.

relaxicons regenerate --manifest relaxicons.manifest --concurrency 4

update-cache

Refresh local cache for collections and icons to improve offline and faster lookup.

relaxicons update-cache

cache-clear

Delete the on-disk cache directory (~/.cache/relaxicons, or RELAXICONS_CACHE_DIR).

relaxicons cache-clear

completion [shell]

Output a basic completion script you can source in your shell.

relaxicons completion zsh

Caching

The CLI caches Iconify metadata under ~/.cache/relaxicons (configurable via RELAXICONS_CACHE_DIR). Cache uses ETag and TTL; stale cache is used on network failures, and requests time out after 15s and retry on rate-limit/5xx responses. Set RELAXICONS_OFFLINE=1 to force offline mode (errors on cache miss). Clear it with relaxicons cache-clear.

Exit Codes

Suggestions

If an icon isn’t found, similar names (Levenshtein-lite character overlap) are displayed.

Example:

relaxicons add lucide:alrm-clock
# => Icon not found. Did you mean: alarm-clock, alarm-check, alarm-off ?

Component Naming

Icon IDs like alarm-clock become AlarmClockIcon via PascalCase + Icon suffix.

Barrel Export

A barrel index.ts (or .js) is updated automatically on each add for React, Next, Vue, Svelte, Solid, and Angular. remove deletes the matching export line. Laravel, Web Components, and --raw output are not barrelled.

Environment

Works with Node 18+.

Advanced Usage

Framework-specific installs

Troubleshooting

• Caching: If collections or icons seem stale, run relaxicons update-cache or delete ~/.cache/relaxicons.
• Rate limits: The CLI retries and uses cache on failures; try again later or use RELAXICONS_OFFLINE=1 when cache is warm.
• Offline mode: Set RELAXICONS_OFFLINE=1 to use cache only (errors on cache miss).

Install the framework runtime in your app if not already present:

# React / Next.js
npm i react react-dom
npm i next   # if using Next.js

# Vue
npm i vue

# Angular
npm i @angular/core

# Svelte
npm i svelte

# Solid
npm i solid-js

# Web Components
# No framework dependency required

Force overwrite

relaxicons add lucide:home --force

Replaces existing component file and re-appends export (duplicate lines cleaned).

Raw SVG output

relaxicons add lucide:star --raw

Writes star.svg transformed (dimensions stripped, currentColor applied) inside outDir.

Temporary framework override

relaxicons add lucide:bolt --framework vue

Generates a Vue SFC even if config framework is React.

Supported values: react, next, next-rsc, vue, angular, laravel, svelte, solid, webc.

Batch add (shell expansion)

for icon in home star bell; do relaxicons add lucide:$icon; done

Listing and searching with grep

relaxicons icons lucide | grep clock
relaxicons search clock | grep lucide

Example Commands Cheatsheet