Installing Packs

Prerequisites

Node.js 18+
A project using React, Vue, or React Native / Expo
A published icon pack identifier like acme/brand/core-icons

Install commands

React:

npx @icon-forge/cli install acme/brand/core-icons --framework react

Vue:

npx @icon-forge/cli install acme/brand/core-icons --framework vue

React Native / Expo:

npx @icon-forge/cli install acme/brand/core-icons --framework react-native

If this is your first install (no iconforge.json yet), passing --framework makes the command copy-pasteable in any environment. After the first run, the CLI saves your framework and output directory so you usually won’t need to pass them again.

On install, the CLI:

Resolves the published manifest for the pack
Downloads the release archive
Writes one component file per slot
Generates a barrel index.ts
Creates or updates iconforge.json and iconforge-lock.json

Typical output:

Install
  Pack:        acme/brand/core-icons
  Framework:   react
  Version:     latest
  API:         https://app.iconforge.ai
> Fetching manifest
> Downloading archive
> Writing 42 components
> Generating barrel
> Replacing install directory

Done
  Pack:        acme/brand/core-icons
  Release:     8f3a9c2d14be
  Framework:   react
  Components:  42
  Output:      src/components/icons/core-icons/

First install

If iconforge.json doesn’t exist yet, the CLI creates it and walks you through setup — it’ll ask for your framework, confirm the output directory, and anything else it needs. Your answers are saved so you won’t be asked again.

In CI or other non-interactive environments, pass the required options as flags instead (e.g., --framework react).

What gets written

src/components/icons/core-icons/
├── ArrowLeft.tsx      # or .vue for Vue
├── CheckCircle.tsx
├── Home.tsx
├── Settings.tsx
├── ...
└── index.ts

Each file is a self-contained component with inline SVG. React and Vue installs have no runtime dependency; React Native installs use react-native-svg.

Output directory

By default, packs are written to src/components/icons/<pack-slug>/.

Customize with:

# Change the base output directory
npx @icon-forge/cli install acme/brand/core-icons --output-dir src/icons

# Override just the pack's folder name
npx @icon-forge/cli install acme/brand/core-icons --dir-name ui-icons

--output-dir sets the shared base directory for all packs
--dir-name overrides the leaf folder for this specific pack

So you can keep a stable base like src/components/icons/ while giving each pack a shorter local name like core/ or nav/.

Common flags

Flag	Purpose
`—framework react	vue
`--output-dir PATH`	Change the base directory where packs are installed
`--dir-name NAME`	Override just this pack’s folder name
`--version HASH`	Install a specific 12-character release hash instead of `latest`
`--force`	Overwrite unrelated conflicting files
`--skip`	Leave conflicting files in place and install only new files
`--dry-run`	Preview the install without writing files
`--api-url URL`	Point the CLI at a local or staging backend for that run

Conflict handling

When files already exist at the destination, the CLI distinguishes between files it owns (tracked in the lockfile) and unrelated files that happen to be in the way.

Flag	Behavior
`--force`	Overwrite unrelated conflicting files
`--skip`	Skip conflicts, install only non-conflicting files
`--dry-run`	Show what would happen without writing anything
(default)	Error with a clear conflict message

Tracked files from a previous install of the same pack are always replaced — that’s a reinstall, not a conflict.

Pinning a release

By default, the CLI installs the latest published release for the pack. To lock to a specific immutable release hash:

npx @icon-forge/cli install acme/brand/core-icons --version 8f3a9c2d14be

See Updating & Pinning for the full workflow.

Pointing at a different API

The CLI defaults to https://app.iconforge.ai. For local development or staging:

npx @icon-forge/cli install acme/brand/core-icons --api-url http://127.0.0.1:7000

Or via environment variable:

ICONFORGE_API_URL=http://127.0.0.1:7000 npx @icon-forge/cli install acme/brand/core-icons

The API URL is not persisted in config — it only affects that run.

If you need the raw manifest and artifact endpoints behind the CLI, see API Reference.