CLIdeveloper-toolsoffline

CLI Tools: Generate Favicons Locally for Offline or Trade-Free Environments

UUnknown

2026-02-13

9 min read

Generate full favicon packs locally with a CLI-first workflow for offline, trade-free distributions—scripts, CI examples, and security tips for devs.

Stop relying on web UIs for favicons — generate them locally, reliably, and trade-free

Hook: If you ship privacy-first distributions, air-gapped appliances, or trade-free Linux images, you can’t depend on cloud-based icon generators or third-party CDNs. Yet creating every required favicon size, format, manifest and HTML snippet manually wastes developer time and invites subtle bugs across browsers and PWAs. This guide shows a practical, CLI-first workflow — using the favicon.live CLI or open-source tooling — so you can produce compliant favicon packs entirely offline and integrate them cleanly into build pipelines and CI/CD.

Why a CLI workflow matters in 2026

Late 2025 and early 2026 saw two trends that matter to icon generation:

Renewed interest in privacy- and trade-free distributions (example: community-driven Linux spins emphasizing zero telemetry and offline installs).
Broader PWA and manifest adoption across desktop and mobile browsers, plus expanded support for maskable and adaptive icons that require precise assets.

As a result, teams need a repeatable local process that outputs all required assets, meta tags, and manifests — with deterministic, auditable tooling you can pin and vet. Treat this like any other supply-chain problem: pin versions, generate an SBOM, and keep a reproducible environment for builds (see guides on security & marketplace changes and hybrid edge workflows for runner/container patterns).

Goals for a production-grade CLI favicon workflow

Offline-first: No external API calls or telemetry during generation.
Deterministic: Pin versions, produce identical outputs across runs for reproducible builds — combine pinned toolchains with deterministic artifact storage and immutable releases.
Comprehensive: Generate icons for legacy browsers, iOS, Android, PWAs, Windows tile images, and SVG/ICO as needed.
Integrable: Fit into npm scripts, Makefiles, Docker builds, and GitHub/GitLab CI without internet access.
Secure: Verify tool fingerprints, use metadata automation for inventories like SBOMs, and favor open-source tools you can audit.

Option A — favicon.live CLI (recommended for teams wanting polished UX + offline mode)

The favicon.live CLI (released with offline mode in 2025) gives a single-command experience for generating full favicon packs locally. It produces assets, a ready-to-use manifest, and an HTML integration snippet — with a flag to disable network calls so nothing leaves your build environment.

Install (example)

Install the cross-platform binary or npm wrapper and verify checksum before use:

# install via npm (developer distro) or download the binary
npm install --save-dev @faviconlive/cli@stable

# verify checksum (example)
sha256sum node_modules/@faviconlive/cli/bin/favicon-live | grep <expected-checksum>

Generate a full offline favicon pack

One command creates the asset directory without any cloud calls:

# source: ./brand/logo.png (high-res, square, 1024x1024 recommended)
npx favicon-live generate ./brand/logo.png --out=dist/icons --offline --manifest --html-snippet

Outputs you'll find in dist/icons:

favicon.ico (multi-resolution ICO)
android-chrome-192.png, android-chrome-512.png
apple-touch-icon.png (180x180)
maskable PNGs, safari pinned tab SVG
manifest.webmanifest
_favicon-snippet.html (pre-made <link>/<meta> tags)

CLI flags to know

--offline — refuse outbound network connections and use local encoders.
--seed-size — set a source size (default 1024), useful for deterministic cropping.
--platforms — choose which platforms to include (pwa, apple, windows, firefox).
--optimize — run local lossless optimization (uses bundled zopflipng/oxipng).

Pro tip: Keep a checked-in dist/icons/.generated-manifest.json so reviewers can diffs for visual changes during code review.

Option B — Open-source stack (full control, ideal for trade-free distros)

If you prefer pure open-source components (no vendor binaries), use a small toolchain: sharp for image transforms, favicons (npm package) for the manifest and legacy packs, and pwa-asset-generator for additional PWA-specific assets. These tools run entirely locally and are auditable.

Minimal Node.js script (offline)

Install pinned versions and commit your lockfile:

npm init -y
npm install --save-dev sharp@0.33.0 favicons@6.2.0 pwa-asset-generator@6.1.0

Example script: scripts/gen-favicons.js

const fs = require('fs');
const favicons = require('favicons');
const { generateFavicons } = require('pwa-asset-generator');

const SOURCE = './brand/logo.png';
const OUT = './dist/icons';

(async () => {
  fs.mkdirSync(OUT, { recursive: true });

  // 1) use pwa-asset-generator to produce Android/PWA maskable sizes
  await generateFavicons(SOURCE, OUT, {
    manifest: true,
    index: false,
    // offline-friendly: pwa-asset-generator doesn't fetch anything
  });

  // 2) use favicons package for legacy icons and .ico
  const configuration = {
    path: '/',
    appName: 'MyApp',
    icons: {
      android: true,
      appleIcon: true,
      favicons: true,
      windows: true,
      firefox: true
    }
  };

  favicons(SOURCE, configuration, (error, response) => {
    if (error) throw error;
    response.images.forEach(img => fs.writeFileSync(`${OUT}/${img.name}`, img.contents));
    response.files.forEach(file => fs.writeFileSync(`${OUT}/${file.name}`, file.contents));
    fs.writeFileSync(`${OUT}/snippet.html`, response.html.join('\n'));
    console.log('Favicons generated to', OUT);
  });
})();

This runs completely locally; no network access required.

Makefile + deterministic build

.PHONY: gen-icons

gen-icons:
	node scripts/gen-favicons.js
	git add dist/icons
	@echo "icons generated"

Integration into CI / CD (air-gapped or trade-free)

CI often has network access — but trade-free builds require reproducible artifacts without external calls. Two best practices:

Cache dependencies in your CI so the generator runs offline. Use an internal npm registry (Verdaccio) or package cache.
Run generators inside a pinned container that carries the exact runtime and tool versions for determinism — follow patterns from hybrid/edge workflows to make your self-hosted runners reproducible.

GitHub Actions (air-gapped runner example)

name: Generate Favicons

on:
  push:
    paths:
      - 'brand/**'

jobs:
  gen:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4
      - name: Restore npm cache
        uses: actions/cache@v4
        with:
          path: ~/.npm
          key: node-modules-${{ hashFiles('package-lock.json') }}
      - name: Install dependencies (offline)
        run: npm ci --offline
      - name: Generate icons
        run: npm run gen-icons
      - name: Commit icons
        run: |
          git config user.name "CI"
          git config user.email "ci@example.com"
          git add dist/icons || true
          git commit -m "chore: regenerate icons" || true
          git push || true

Note: run this on self-hosted (air-gapped) runners that have your cached dependencies and toolchain preloaded.

CMS / Build pipeline integration tips

Generate icons at build time and include them in your static assets. For CMS-driven sites, add a small management page for replacing the seed image; run the CLI in your build pipeline on deploy.
Store the generated snippet (snippet.html) and reference it during server-side rendering to avoid runtime generation.
If you need a developer preview inside the CMS, run a local static server (http-server) and open the snippet in a headless browser (Puppeteer) to produce preview screenshots for the content editors — combine this with automated metadata tooling (see DAM/metadata automation) to keep inventories accurate.

Best practices: formats, sizes, caching and SEO

Must-have files

favicon.ico — legacy desktop browsers and older Windows clients (include 16x16, 32x32, 48x48 inside the ICO).
android-chrome-192.png and android-chrome-512.png — required for PWA installability.
apple-touch-icon.png — 180x180 for iOS home screen.
maskable icons — include maskable PNGs and specify purpose: ["any","maskable"] in the manifest.
safari-pinned-tab.svg — for Safari pinned tabs (monochrome, provide theme color).

Manifest and meta tags

Include a manifest.webmanifest with correctly populated icons array. Add meta tags in your template (extract from generated snippet):

<link rel="manifest" href="/icons/manifest.webmanifest">
<link rel="icon" href="/icons/favicon.ico" sizes="any">
<link rel="apple-touch-icon" href="/icons/apple-touch-icon.png">
<meta name="theme-color" content="#0a84ff">

Caching

Set long Cache-Control for static icon files (e.g., Cache-Control: public, max-age=31536000, immutable).
When you change icons, change file names (hash them) or update references via a release process so clients fetch the new images. Storing versioned CI artifacts in a release helps audits and reduces accidental cache staleness.
For manifests and snippet HTML, you can use shorter caching but ensure the build/deploy updates the path or version to force refresh.

SEO & performance notes

Favicons have minimal direct SEO impact, but consistent branding can improve CTRs and detectability in shared bookmarks and SERPs.
Keep icons optimized: modern encoders (oxipng, zopflipng, svgo) reduce bytes with no visual loss.
Bundling large PNGs inline as data URIs is not recommended — they increase HTML size and block rendering.

Security, supply-chain and trade-free considerations

In trade-free or privacy-focused distros you should:

Pin tool versions in package-lock.json or container images.
Verify checksums for any binary you add to the image — run the same due-diligence processes you use for domains and vendor provenance (due diligence guides are a useful cross-reference).
Prefer open-source tooling you can vendor (store in your internal registry or binary repo) so no build-time network calls are needed.
Generate SBOM for your build artifacts to meet audit requirements — tie this into metadata extraction workflows (DAM/metadata automation).
Run icon generation in a reproducible environment (deterministic Docker image or self-hosted runner) to avoid hidden network dependencies — patterns in hybrid edge workflows are helpful here.

Small detail: a single missing apple-touch-icon can make your OS home-screen shortcut look pixelated. The CLI approach eliminates human error.

Live preview locally (developer-friendly)

Even in an offline environment you want a quick preview. Use a tiny local server and an auto-generated preview HTML:

# install a small static server
npm install --save-dev http-server

# serve the icons folder and open a preview (headless)
http-server dist/icons -p 8088 &
# open http://localhost:8088/preview.html in a browser or use puppeteer to screenshot

Automate screenshot previews in CI so designers can review generated icon assets without internet.

Advanced strategies & future-proofing (2026+)

SVG-first design: Start with a well-crafted SVG logo; produce raster derivatives from vector for crisp results on all DPIs. (See a workflow for turning daily vector assets into archival outputs: vector-to-archive workflow.)
Adaptive icon generator: Export separate foreground/background layers if you support Android adaptive icons in the future.
Automated QA: Add a lint step that validates manifest icons include maskable entries and that PNGs meet size/ratio checks — integrate this with your metadata/SBOM tooling (metadata automation).
Versioned CI artifacts: Store generated icon packs as release assets so installations can be fully offline and reproducible — plan for storage and cost using a storage-cost strategy.

Quick checklist before you ship

Seed image is square and >= 1024px.
Manifest has maskable icons and correct purpose flags.
favicon.ico contains multiple sizes.
All generated files are served with long, immutable caching.
Toolchain is pinned and available offline through your internal registry.

Actionable takeaway — a runnable recipe

Pick: favicon.live CLI (easy, offline mode) or open-source stack (sharp + favicons + pwa-asset-generator).
Vendor the chosen tools into an internal repo/binary cache and pin versions.
Add a simple npm script: "gen-icons": "node scripts/gen-favicons.js".
Run locally, commit dist/icons to a release branch, and add a CI job that reproduces the build in an air-gapped runner.
Set cache headers and release with hashed filenames when deploying to production.

Why this matters now

As 2026 progresses, more organizations choose privacy-preserving, offline-capable products. A CLI-first favicon workflow aligns with that shift: it removes hidden dependencies, ensures reproducibility, and reduces manual effort while producing pixel-perfect icons across platforms.

Next steps — try it today

Get started in minutes: if you prefer a turnkey, audited option use the favicon.live CLI in offline mode; if you want full control, follow the Node.js script above using sharp, favicons, and pwa-asset-generator. Either way, integrate generation into your build process so icons are always correct, cached, and auditable.

Need a template repo, CI snippets, or a Docker image for air-gapped builds? Visit the favicon.live docs or clone the example repo for an opinionated, trade-free starter kit and integrate it into your distro or appliance build today.

Call to action: Choose a path — try the favicon.live CLI offline mode or clone the open-source example and run the gen-icons script. Commit the outputs to your release pipeline and ship consistent, privacy-respecting favicons with confidence.

Unknown

Contributor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.