@svgicons-com/cli 0.1.0-alpha.3 → 0.1.0-alpha.4

package/README.md

@@ -60,6 +60,7 @@ svgicons icon show 33716
 svgicons icon url 33716-arrow-circle-up-fill
 svgicons icon raw 33716-arrow-circle-up-fill
 svgicons icon download 33716-arrow-circle-up-fill --output ./icons
+svgicons icon png 33716-arrow-circle-up-fill --size 512 --output ./icons
 svgicons collection list
 svgicons collection create --name "Dashboard icons" --description "Navigation and status icons"
 svgicons collection show "Dashboard icons" --icons
@@ -69,6 +70,7 @@ svgicons collection add "Dashboard icons" 33716 240297
 svgicons collection remove "Dashboard icons" 33716-arrow-circle-up-fill
 svgicons collection delete "Dashboard icons" --yes
 svgicons collection export "Dashboard icons" --formats react-ts,vue --color-policy currentColor --output ./exports
+svgicons collection export "Dashboard icons" --formats png-pack --png-sizes 24,48,512 --output ./exports
 svgicons collection export "Dashboard icons" --formats react-ts --no-size-props --no-typescript --output ./exports
 svgicons export status 55 --collection "Dashboard icons"
 svgicons export download 55 --collection "Dashboard icons" --output ./exports
@@ -116,6 +118,16 @@ The icon reference must include both the numeric ID and the icon name, such as `
 
 This command uses the MCP `get_icon` tool with raw SVG output, so the token needs `mcp:use` and `icons:read`. Existing files are not overwritten unless you add `--force`.
 
+Export a Pro PNG asset from a single icon:
+
+```bash
+svgicons icon png 33716-arrow-circle-up-fill --size 512 --output ./icons
+svgicons icon png 33716-arrow-circle-up-fill --sizes 128,256,512 --density 1,2 --zip --output ./icons
+svgicons icon png 33716-arrow-circle-up-fill --size 512 --color black --background solid --background-color "#ffffff"
+```
+
+Single-icon PNG export uses the Pro REST API, not the public anonymous search API. The token needs `icons:read` and `exports:create`. The icon reference must include both ID and name, and the server verifies that the name matches before rendering.
+
 Read-only icon commands accept a numeric ID, an `id-name` reference, or a full svgicons.com icon URL:
 
 ```bash
@@ -174,13 +186,22 @@ The command polls every 2 seconds for up to 180 seconds by default. Use `--timeo
 Supported export flags:
 
 ```bash
---formats react-ts,vue
+--formats react-ts,vue,png-pack
 --color-policy currentColor|preserve|strip
 --naming-policy kebab|pascal|camel
 --size-props / --no-size-props
 --typescript / --no-typescript
+--png-sizes 24,48,512
+--png-densities 1,2
+--png-background transparent|solid
+--png-background-color "#ffffff"
+--png-color preserve|black|white|custom
+--png-icon-color "#2563eb"
+--png-padding 48
 ```
 
+Use `--formats png` as a shorthand for `--formats png-pack`. PNG pack exports are generated by the server queue worker and downloaded as part of the collection ZIP.
+
 Collection commands accept a numeric ID, exact slug, or exact case-insensitive collection name. The legacy `kit` alias remains available for old scripts.
 
 Lifecycle commands are available for collection maintenance:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svgicons-com/cli",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.4",
   "description": "Svg/icons CLI alpha for icon search, Pro collections, exports, project scanning, and license workflows.",
   "type": "module",
   "bin": {

package/src/api.js

@@ -79,14 +79,26 @@ export async function proApiDownload(pathOrUrl, options = {}) {
   let response;
 
   try {
-    response = await fetch(url, {
+    const headers = {
+      Accept: 'image/png, application/zip, application/octet-stream',
+      Authorization: `Bearer ${token}`,
+      'User-Agent': 'svgicons-cli/0.1.0-alpha',
+      ...options.headers,
+    };
+    const init = {
       method: options.method || 'GET',
-      headers: {
-        Accept: 'application/zip, application/octet-stream',
-        Authorization: `Bearer ${token}`,
-        'User-Agent': 'svgicons-cli/0.1.0-alpha',
-        ...options.headers,
-      },
+      headers,
+    };
+
+    if (options.body !== undefined) {
+      headers['Content-Type'] = headers['Content-Type'] || 'application/json';
+      init.body = typeof options.body === 'string' || options.body instanceof Buffer
+        ? options.body
+        : JSON.stringify(options.body);
+    }
+
+    response = await fetch(url, {
+      ...init,
     });
   } catch (error) {
     throw networkError(error, url);

package/src/cli.js

@@ -22,6 +22,7 @@ import {
   parseIconReference,
   resolveArchiveDownloadPath,
   resolveIconDownloadPath,
+  resolvePngDownloadPath,
   sanitizeFileSegment,
   writeBinaryFile,
   writeIconSvg,
@@ -56,10 +57,15 @@ const KNOWN_SCOPES = [
   'exports:create',
   'mcp:use',
 ];
-const EXPORT_FORMATS = ['svg-folder', 'svg-sprite', 'json-manifest', 'license-manifest', 'react-ts', 'vue'];
+const EXPORT_FORMATS = ['svg-folder', 'svg-sprite', 'json-manifest', 'license-manifest', 'react-ts', 'vue', 'png-pack'];
 const FRAMEWORKS = ['svg', 'react-ts', 'vue', 'sprite'];
 const COLOR_POLICIES = ['currentColor', 'preserve', 'strip'];
 const NAMING_POLICIES = ['kebab', 'pascal', 'camel'];
+const PNG_SIZES = [16, 24, 32, 48, 96, 128, 256, 512, 1024];
+const PNG_DENSITIES = [1, 2, 3, 4];
+const PNG_BACKGROUNDS = ['transparent', 'solid'];
+const PNG_COLORS = ['preserve', 'black', 'white', 'custom'];
+const PNG_FITS = ['contain'];
 
 export async function run(argv) {
   const { args, options: globalOptions } = extractGlobalOptions(argv);
@@ -633,7 +639,12 @@ async function icon(args) {
     return;
   }
 
-  throw new Error('Unknown icon command. Use: show, raw, url, open, download.');
+  if (subcommand === 'png') {
+    await iconPng(rest);
+    return;
+  }
+
+  throw new Error('Unknown icon command. Use: show, raw, url, open, download, png.');
 }
 
 async function iconShow(args) {
@@ -715,6 +726,40 @@ async function iconDownload(args) {
   console.log(`  ${outputPath}`);
 }
 
+async function iconPng(args) {
+  const options = parseOptions(args);
+  const [iconReference] = options._;
+  const reference = parseIconReference(iconReference);
+  const payload = buildIconPngPayload(reference, options);
+  const download = await proApiDownload(`/api/pro/icons/${encodeURIComponent(reference.id)}/png-export`, {
+    method: 'POST',
+    body: payload,
+    headers: {
+      'Content-Type': 'application/json',
+    },
+  });
+  const outputPath = resolvePngDownloadPath(options.output || options.o, download.filename, process.cwd());
+
+  await writeBinaryFile(outputPath, download.bytes, booleanOption(options.force, false));
+
+  if (options.json) {
+    printJson({
+      icon: {
+        id: reference.id,
+        name: reference.slug,
+      },
+      outputPath,
+      contentType: download.contentType,
+      filename: download.filename,
+      options: payload,
+    });
+    return;
+  }
+
+  console.log(`Downloaded PNG export`);
+  console.log(`  ${outputPath}`);
+}
+
 async function collection(args) {
   const [subcommand, ...rest] = args;
 
@@ -1830,17 +1875,104 @@ function extensionSet(value) {
 }
 
 function buildExportOptions(options) {
+  const formats = exportFormatsOption(options.formats);
+  const png = buildCollectionPngOptions(options);
+  const includesPng = formats?.includes('png-pack') || Object.keys(png).length > 0;
+  const normalizedFormats = includesPng && formats === undefined
+    ? ['png-pack']
+    : formats;
+
   return {
-    formats: enumCsvOption(options.formats, 'export format', EXPORT_FORMATS),
+    formats: normalizedFormats,
     options: {
       colorPolicy: enumOption(options['color-policy'], 'color policy', COLOR_POLICIES),
       namingPolicy: enumOption(options['naming-policy'], 'naming policy', NAMING_POLICIES),
       sizeProps: booleanFlagPair(options, 'size-props', 'no-size-props'),
       typescript: booleanFlagPair(options, 'typescript', 'no-typescript'),
+      png: includesPng ? png : undefined,
     },
   };
 }
 
+function buildIconPngPayload(reference, options) {
+  return {
+    iconName: reference.slug,
+    sizes: integerCsvOption(options.sizes ?? options.size, 'PNG size', PNG_SIZES, [512]),
+    densities: integerCsvOption(options.densities ?? options.density, 'PNG density', PNG_DENSITIES, [1]),
+    backgroundType: enumOption(options.background, 'PNG background', PNG_BACKGROUNDS),
+    backgroundColor: options['background-color'],
+    iconColorMode: enumOption(options.color, 'PNG icon color mode', PNG_COLORS),
+    iconColor: options['icon-color'],
+    padding: integerOption(options.padding, 'PNG padding'),
+    fit: enumOption(options.fit, 'PNG fit mode', PNG_FITS),
+    filename: options.filename,
+    zip: booleanOption(options.zip, undefined),
+  };
+}
+
+function buildCollectionPngOptions(options) {
+  return stripUndefined({
+    sizes: integerCsvOption(options['png-sizes'] ?? options['png-size'], 'PNG size', PNG_SIZES, undefined),
+    densities: integerCsvOption(options['png-densities'] ?? options['png-density'], 'PNG density', [1, 2, 3], undefined),
+    backgroundType: enumOption(options['png-background'], 'PNG background', PNG_BACKGROUNDS),
+    backgroundColor: options['png-background-color'],
+    iconColorMode: enumOption(options['png-color'], 'PNG icon color mode', PNG_COLORS),
+    iconColor: options['png-icon-color'],
+    padding: integerOption(options['png-padding'], 'PNG padding'),
+    fit: enumOption(options['png-fit'], 'PNG fit mode', PNG_FITS),
+  });
+}
+
+function exportFormatsOption(value) {
+  const values = csvOption(value);
+
+  if (!values) {
+    return undefined;
+  }
+
+  const normalized = values.map((item) => item === 'png' ? 'png-pack' : item);
+  const invalid = normalized.filter((item) => !EXPORT_FORMATS.includes(item));
+  if (invalid.length > 0) {
+    throw usageError(`Invalid export format: ${invalid.join(', ')}. Allowed values: ${EXPORT_FORMATS.join(', ')}, png`);
+  }
+
+  return [...new Set(normalized)];
+}
+
+function integerCsvOption(value, label, allowed, fallback) {
+  const values = csvOption(value);
+
+  if (!values) {
+    return fallback;
+  }
+
+  const parsed = values.map((item) => Number(item));
+  const invalid = parsed.filter((item) => !Number.isInteger(item) || !allowed.includes(item));
+
+  if (invalid.length > 0) {
+    throw usageError(`Invalid ${label}: ${invalid.join(', ')}. Allowed values: ${allowed.join(', ')}`);
+  }
+
+  return [...new Set(parsed)];
+}
+
+function integerOption(value, label) {
+  if (value === undefined || value === true || value === '') {
+    return undefined;
+  }
+
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed)) {
+    throw usageError(`Invalid ${label}: ${value}. Expected an integer.`);
+  }
+
+  return parsed;
+}
+
+function stripUndefined(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}
+
 function enumOption(value, label, allowed) {
   if (value === undefined || value === true || value === '') {
     return undefined;
@@ -1894,6 +2026,7 @@ Usage:
   svgicons icon url <icon-ref>
   svgicons icon open <icon-ref>
   svgicons icon download <icon-id-name> [--output ./icons] [--force]
+  svgicons icon png <icon-id-name> [--size 512] [--density 1,2] [--output ./icons] [--force]
   svgicons collection list [--json]
   svgicons collection create --name "Dashboard icons"
   svgicons collection show <collection-id-or-name> [--icons] [--json]
@@ -1902,7 +2035,7 @@ Usage:
   svgicons collection add <collection-id-or-name> <icon-id...>
   svgicons collection remove <collection-id-or-name> <icon-id...>
   svgicons collection delete <collection-id-or-name> [--yes]
-  svgicons collection export <collection-id-or-name> [--formats react-ts,vue] [--no-size-props] [--no-typescript] [--output ./exports]
+  svgicons collection export <collection-id-or-name> [--formats react-ts,vue,png-pack] [--png-sizes 24,48,512] [--no-size-props] [--no-typescript] [--output ./exports]
   svgicons export status <export-id> --collection <collection-id-or-name>
   svgicons export download <export-id> --collection <collection-id-or-name> [--output ./exports]
   svgicons init [--collection <collection-id-or-name>] [--output svgicons-icons]

package/src/downloads.js

@@ -95,6 +95,25 @@ export function resolveArchiveDownloadPath(output, filename, cwd = process.cwd()
   return join(target, safeFilename);
 }
 
+export function resolvePngDownloadPath(output, filename, cwd = process.cwd()) {
+  const safeFilename = sanitizeFileName(filename || 'svgicons-icon.png', 'png');
+
+  if (!output || output === true) {
+    return resolve(cwd, safeFilename);
+  }
+
+  const target = isAbsolute(String(output))
+    ? String(output)
+    : resolve(cwd, String(output));
+
+  const extension = extname(target).toLowerCase();
+  if (extension === '.png' || extension === '.zip') {
+    return target;
+  }
+
+  return join(target, safeFilename);
+}
+
 export async function writeIconSvg(path, svg, force = false) {
   if (!svg || typeof svg !== 'string') {
     throw new Error('The icon response did not include SVG markup.');