Automate SVG Checks and Exports with the CLI

Checking twenty SVGs and exporting three PNG sizes should be one repeatable command, with a failed check stopping the build. IconVectors CLI turns source icons into checked SVG copies, transparent PNGs and a multi-size Windows ICO without opening the Editor.

This guide uses IconVectors 2.20 for Windows and PowerShell. Keep the originals in assets/icons and generate everything under dist/icons. The CLI processes files directly; it does not control an open IconVectors window or require MCP.

1 - Locate the executable

IconVectors installs IconVectorsCli.exe alongside the application, without adding it to PATH. Use the default installation path below, or change $iv to your actual installation folder:

$iv = Join-Path $env:ProgramFiles 'Axialis\IconVectors\IconVectorsCli.exe'
& $iv --version
& $iv command list --format json
& $iv export --help

From that folder, .\IconVectorsCli.exe --help also works. PowerShell's & invocation operator runs an executable stored in a variable or a quoted path.

Use the installed catalog when an agent needs to discover a command. For example, & $iv command describe export --format json returns its typed options and entitlement requirements. Space-separated names such as style apply execute operations; stable dotted IDs are accepted by command describe for discovery.

Help, discovery, inspection, checking and style listing work without activation. Asset generation, including dry runs, requires the current user's existing valid license or unexpired trial. The CLI does not log in, activate or start a trial. Resolve entitlement in IconVectors first, including for the account running an automated build.

2 - Give the source folder a quality gate

Put SVGs in assets/icons, including app.svg for the ICO example. Run from your project root:

$json = & $iv check --input-dir 'assets/icons' --recursive --fail-on warning --format json
$code = $LASTEXITCODE
$result = ($json -join [Environment]::NewLine) | ConvertFrom-Json
$result.diagnostics
if ($code -ne 0) { throw "SVG check failed with exit code $code." }

--recursive includes subfolders; it is never implied. --fail-on warning fails on warnings and errors. Omit it for the default error-only threshold. This command policy is independent of the Editor's strict-checking preference.

Capture $LASTEXITCODE immediately after the executable returns. Read diagnostic codes and locations rather than matching English messages. These are bounded checks of supported SVG syntax and features, not complete W3C conformance validation or visual-design QA.

For a fixed list, use --files-from icons.json containing a UTF-8 JSON array of paths. Relative entries resolve against the list file's folder. Choose one input mode per invocation.

Folder inputs are convenient for a whole icon set; a checked-in list is useful when a build should include only a defined subset. Either way, pass explicit paths and options from your build script instead of relying on a developer's current panel settings.

3 - Preview optimized copies

Keep editable originals separate from shipping assets. This plan lists intended optimized copies and diagnostics without creating asset folders, copies or backups:

& $iv optimize --input-dir 'assets/icons' --recursive --output-dir 'dist/icons/svg' --dry-run --format json

Review outputs and diagnostics, then remove --dry-run to create the copies. Relative subfolders and filenames are retained. Optimization is conservative; it is not a sanitizer.

A dry run does not reserve destinations or guarantee later writes. Execution takes a fresh snapshot and validates again, which matters if an editor or another build changes the files.

4 - Save a build script

Save this as build-icons.ps1 in the project root, beside assets. It checks the inputs, plans and creates optimized SVGs, exports three PNG sizes, then builds one ICO containing seven sizes. Each step must succeed before the next starts.

$ErrorActionPreference = 'Stop'
$iv = Join-Path $env:ProgramFiles 'Axialis\IconVectors\IconVectorsCli.exe'
if (-not (Test-Path -LiteralPath $iv -PathType Leaf)) {
    throw 'Set $iv to the installed IconVectorsCli.exe.'
}

function Invoke-IconVectors {
    param([string[]]$CliArguments)

    $json = & $iv @CliArguments
    $code = $LASTEXITCODE
    if ($code -ne 0) {
        Write-Host ($json -join [Environment]::NewLine)
        throw "IconVectors CLI failed with exit code $code."
    }
    return (($json -join [Environment]::NewLine) | ConvertFrom-Json)
}

Push-Location -LiteralPath $PSScriptRoot
try {
    $check = Invoke-IconVectors -CliArguments @(
        'check', '--input-dir', 'assets/icons', '--recursive',
        '--fail-on', 'warning', '--format', 'json'
    )
    $optimize = @(
        'optimize', '--input-dir', 'assets/icons', '--recursive',
        '--output-dir', 'dist/icons/svg', '--format', 'json'
    )
    $plan = Invoke-IconVectors -CliArguments ($optimize + @('--dry-run'))
    Write-Host "Optimization plan: $($plan.status)"
    $svg = Invoke-IconVectors -CliArguments $optimize

    $png = Invoke-IconVectors -CliArguments @(
        'export', '--input-dir', 'dist/icons/svg', '--recursive',
        '--type', 'png', '--sizes', '24,48,96',
        '--current-color', '#383838',
        '--output-dir', 'dist/icons/png', '--format', 'json'
    )
    $ico = Invoke-IconVectors -CliArguments @(
        'export', '--input', 'dist/icons/svg/app.svg',
        '--type', 'ico', '--sizes', '16,24,32,48,64,128,256',
        '--output', 'dist/icons/app.ico', '--format', 'json'
    )
    Write-Host "SVG: $($svg.status); PNG: $($png.status); ICO: $($ico.status)"
}
finally {
    Pop-Location
}

Run .\build-icons.ps1, or call the saved script from an IDE task or build runner. Working paths resolve from the script's folder. Its dry run is an extra preflight, not an approval prompt; use the separate preview command above to inspect a plan interactively first.

This is ordinary shell sequencing. Each CLI invocation handles one operation, and PowerShell decides whether to continue. There is no native pipeline or saved-plan command to configure. Keep this script in version control with the icon sources so the required sizes and output paths are reviewed alongside code changes.

PNG filenames include their sizes, such as navigation/save-24x24.png. The ICO is one file containing all requested sizes. --current-color '#383838' provides a fallback for inherited currentColor; it does not recolor authored fills or strokes. Authored color context is retained.

--type selects PNG or ICO; --format json selects the terminal report. CLI raster export rejects pattern, mask and clipPath definitions, including unused ones. Follow unsupported-content diagnostics rather than assuming every SVG can use this export path.

5 - Make repeat builds deliberate

The first run creates outputs. A second run into the same destination normally fails because existing files are protected. After confirming that dist/icons contains only generated assets, add '--overwrite' to the optimization arguments and both export argument arrays for repeat builds.

This authorizes replacement of validated outputs only. It cannot replace source SVGs, an input list or a supplied Styles library. After a failure, read the diagnostics: an I/O or recovery error can leave disclosed outputs or recovery files. Nonzero does not mean nothing was written.

Stop on every nonzero code, including codes omitted from this table. The full exit-code reference also covers input, capability, cancellation and internal failures.

Keep reports and reuse team Styles

For a persistent JSON report, create its parent first, then add --report. Report format is always JSON, regardless of terminal format. Existing reports require explicit overwrite permission too.

New-Item -ItemType Directory -Path 'reports' -Force | Out-Null
& $iv check --input-dir 'assets/icons' --recursive --fail-on warning --format json --report 'reports/icon-check.json'
$code = $LASTEXITCODE
if ($code -ne 0) { throw "SVG report command failed with exit code $code." }

Keep stdout and the exit code in build logs as well. Invalid arguments or denied entitlement may prevent a report. Report-writing failure can happen after assets commit; the result discloses that outcome rather than claiming those assets were rolled back.

After exporting a team Styles library, run & $iv style list --library 'team.axstyle' --format json to discover its keys. Use style apply --library 'team.axstyle' --style-key YOUR_KEY with explicit SVG inputs and a new destination. Keys are case-sensitive, not display names. The CLI reads the supplied file, not the library selected in the panel.

You now have a script that stops on a quality failure and builds separate assets from your source icons. Keep the input bytes, options and CLI version consistent for repeatability, and visually check representative outputs at their real display size. The CLI reference covers the other transforms and color operations.