Command-Line Interface

The command-line interface is a separate console program: IconVectorsCli.exe on Windows and iconvectors-cli on macOS/Linux. It processes SVG files directly, without opening the Editor, changing its current document, or connecting to the MCP server.

Use it from a terminal, IDE task, build script or local agent to inspect SVGs, check supported syntax, create transparent PNGs and multi-size ICOs, or produce SVG copies with reusable Styles, geometry, color and stroke adjustments. This includes resizing canvases, creating Hot/Disabled/Dark versions, applying palettes or gradients, and converting supported strokes to filled outlines. The supported commands are listed below.

Starting the CLI 

Run the executable from the IconVectors installation, using its full path if it is not on your shell’s PATH. Installing IconVectors does not silently add the CLI to PATH. In a Windows source build, the Release executable is alongside IconVectors.exe in build/x64/Release or build/Win32/Release.

For example, in PowerShell from the executable’s directory:

.\IconVectorsCli.exe --version
.\IconVectorsCli.exe --help
.\IconVectorsCli.exe export --help

The following examples use IconVectorsCli.exe for readability. Use ./IconVectorsCli.exe in PowerShell when it is in the current directory, or replace it with a quoted full path preceded by &. On macOS/Linux use iconvectors-cli instead. The macOS application build registers the helper at IconVectors.app/Contents/Helpers/iconvectors-cli; a Linux package registers it in the executable installation directory.

Help, version, command discovery, inspect, check, style list and style inspect do not require an activated license or start a trial. All asset-generating commands, including their dry runs, require the current user’s existing valid IconVectors activation, offline license or unexpired trial. The CLI shares the product’s local entitlement checks; it does not log in, activate, initialize a trial, display a question or contact an activation server. If rights are unavailable or reactivation is required, launch IconVectors to resolve that condition, then retry. See Licensing.

Selecting inputs and destinations 

Choose exactly one input mode:

--input "file.svg": one explicit SVG. Repeat --input for several files.
--input-dir "assets": SVGs directly inside a folder. Add --recursive to include subfolders; recursion is never implicit.
--files-from "icons.json": a UTF-8 JSON array of paths. Relative entries are resolved against the list file’s folder, not the shell’s working folder.

For example, icons.json can contain:

["assets/save.svg", "assets/open.svg", "assets/toolbar/print.svg"]

Quote paths containing spaces and quote hexadecimal colors, particularly in shells where # starts a comment. Use explicit files or a folder rather than depending on shell-specific wildcard expansion. Unknown options, repeated nonrepeatable options and unexpected positional arguments are errors.

Asset-generating commands also require exactly one destination:

--output "dist/app.ico" specifies an exact filename and requires a single generated artifact. A multi-size ICO is one artifact; several PNG sizes are not.
--output-dir "dist" supplies a destination root. Directory inputs retain their relative subfolder structure. Different explicit files that would produce the same output name cause a conflict instead of being overwritten.

The output extension must match the requested format. Required asset folders can be created under the explicit destination during execution, not during a dry run. Existing outputs are protected unless you pass --overwrite. Neither that flag nor an exact filename permits replacing any input SVG, the input-list document or a supplied style/palette library. All SVG-generating operations are copy-only in this version. Under --output-dir, optimization, styling and one-result transformations retain the input’s filename without adding a suffix; choose a distinct destination folder. make-versions uses its fixed version suffixes under --output-dir.

Discovering commands 

IconVectorsCli.exe command list --format json
IconVectorsCli.exe command describe export --format json
IconVectorsCli.exe command describe svg.check --format json
IconVectorsCli.exe command describe style.apply --format json
IconVectorsCli.exe command describe icon.fit --format json

The executable’s command catalog is the machine-readable reference for its installed version. Each descriptor provides its stable ID, typed argument schema, defaults, result shape, capabilities, output/transaction behavior and entitlement requirements. Both the short command and stable ID are accepted by command describe. To run an operation, use its short command.

Implemented operation catalog
Command	Stable ID	Purpose
`inspect`	`svg.inspect`	Read supported dimensions, element and paint information.
`check`	`svg.check`	Check supported SVG syntax and report located findings.
`export`	`icon.export`	Generate transparent PNG variants or a multi-size ICO.
`optimize`	`svg.optimize`	Write conservatively optimized SVG copies.
`style list`	`style.list`	List style keys and names in an explicit library.
`style inspect`	`style.inspect`	Read a saved style’s complete appearance snapshot.
`style apply`	`style.apply`	Apply a saved complete style, Fill only or Stroke only to SVG copies.
`transform center`	`icon.center`	Center complete artwork on its existing canvas.
`transform fit`	`icon.fit`	Proportionally fit artwork inside equal canvas margins.
`transform rotate`	`icon.rotate`	Rotate complete artwork by a finite signed angle.
`transform flip`	`icon.flip`	Flip complete artwork horizontally or vertically.
`color replace`	`color.replace`	Replace an effective solid RGB or symbolic `currentColor` paint.
`color current-color`	`color.to-current-color`	Convert all, or one matching RGB, solid paints to `currentColor`.
`stroke`	`stroke.change`	Change width, caps, joins or color on existing strokes.
`outline-strokes`	`icon.outline-strokes`	Convert supported whole-icon strokes to filled paths in SVG copies.
`resize`	`icon.resize`	Resize the source canvas proportionally into a centered new canvas.
`make-versions`	`icon.make-versions`	Create Hot, Disabled and/or Dark Theme SVG copies.
`palette apply`	`color.apply-palette`	Map supported colors to an explicit Axialis palette file.
`auto-gradient`	`paint.auto-gradient`	Apply same-tone gradients to supported fill/stroke paints.

This catalog is separate from the live MCP tool catalog. There are no app, project build, scripting, saved-plan or in-place-editing commands in CLI v1. Nested commands use space-separated words when executed; dotted IDs are accepted by command describe, not as execution aliases.

Inspecting and checking SVGs 

IconVectorsCli.exe inspect --input "assets/save.svg" --format json
IconVectorsCli.exe check --input-dir "assets" --recursive --format json
IconVectorsCli.exe check --files-from "icons.json" --fail-on warning

inspect reports supported source information and diagnostics without modifying the file. check additionally runs the shared strict SVG checks. Findings can include a stable code, severity, path and source location when known. They are bounded checks of the syntax and features understood by IconVectors, not complete W3C conformance validation or visual-design QA. Passing a check is not a guarantee that every browser or renderer displays an SVG identically.

For check, the default --fail-on error reports warnings without making warnings alone fail the command. Use --fail-on warning to fail on either warnings or errors. This explicit CLI policy does not read or change the Editor’s strict-checking preference. Asset-generating operations retain their own mandatory input/security checks; they do not inherit that Editor preference or acquire its optional warning gate.

Creating PNG and ICO files 

IconVectorsCli.exe export --input "assets/app.svg" --type ico --sizes 16,24,32,48,64,128,256 --output "dist/app.ico"
IconVectorsCli.exe export --input-dir "assets" --recursive --type png --sizes 24,48,96 --output-dir "dist/png" --current-color "#383838" --format json

With --output-dir, --type png creates one transparent PNG per source and size, named for example save-24x24.png. --type ico creates one ICO per source, for example save.ico, containing all requested square sizes with 32-bit alpha transparency. Sizes must be unique positive integers: 1–2048 pixels for PNG, 1–256 for ICO, with at most 32 sizes in one invocation.

--current-color "#RRGGBB" supplies an opaque fallback for inherited currentColor; its default is black. Authored color context is retained. This is not a command to replace every authored fill or stroke. Rendering uses the shared production SVG/raster path, including supported aspect-ratio behavior on a square output canvas. See also the interactive Make Bitmap Icons batch feature.

CLI v1 raster export rejects SVGs containing pattern, mask or clipPath definitions, including unused definitions. The current renderer can allocate intermediate surfaces from their authored extents independently of the small requested output size; the CLI does not enter that unbounded allocation path. This is an explicit CLI safety limit, not a claim that those SVG features are invalid or unsupported by the Editor/MCP. check reports the same limit as an error, while inspect reports a warning and continues source inspection. Copy-only optimize does not render the icon and remains subject to the conservative optimizer’s own supported-content rules. Styling, geometry and paint commands also use their own supported-content policies; the raster-only restriction does not automatically prohibit a source edit.

Creating Hot, Disabled and Dark Theme versions 

make-versions requires --versions with one or more unique names from hot,disabled,dark, separated by commas. Each version is generated independently from the original SVG, in Hot, Disabled, Dark order regardless of the order in the argument. It acts on the complete icon, not selected IDs.

IconVectorsCli.exe make-versions --input-dir "assets" --versions hot,disabled,dark --output-dir "dist/versions" --dry-run --format json
IconVectorsCli.exe make-versions --input-dir "assets" --versions hot,disabled,dark --output-dir "dist/versions" --format json
IconVectorsCli.exe make-versions --input "assets/app.svg" --versions disabled --output "dist/app-disabled.svg"

Under --output-dir, fixed suffixes produce names such as app-hot.svg, app-disabled.svg and app-dark.svg, preserving directory-relative subfolders. There is no custom-suffix option. --output is available only for one source and one selected version. The 8,192-artifact limit applies to the number of sources multiplied by the selected version count; exceeding it rejects the job before writing files.

These are the existing Icon version algorithms, not automatic aesthetic or accessibility adjustments. Hot changes color levels; Disabled desaturates and applies the existing disabled-opacity policy; Dark Theme changes lightness while retaining hue/saturation. Symbolic currentColor remains symbolic. In particular, Disabled can add opacity 0.5 to explicitly painted elements, including symbolic paints, even when no RGB value changes. Existing explicit opacity follows the shared policy rather than being blindly multiplied on every node.

Geometry, unrelated XML and supported color/context/alpha semantics are retained. Unsupported source or a failed version blocks the complete copy job; the CLI does not silently omit that version. Review per-output results and diagnostics. A source counts as unchanged only when all its requested versions retain its original bytes; unchanged content can still produce a new output copy.

Optimizing SVG copies 

IconVectorsCli.exe optimize --files-from "icons.json" --output-dir "dist/svg" --dry-run --format json
IconVectorsCli.exe optimize --files-from "icons.json" --output-dir "dist/svg" --format json
IconVectorsCli.exe optimize --input "assets/save.svg" --output "dist/save.svg" --round-coordinates --decimal-places 4

The default policy compacts formatting, hexadecimal paint colors and path numbers while preserving supported metadata, comments, IDs and references. It uses the same conservative optimizer as Batch Optimize SVG Files. If the supported transformation does not make a file smaller, the output copy retains its original bytes. Unsupported content produces a diagnostic rather than being silently stripped.

Coordinate rounding is off by default because it can change appearance. Opt in with --round-coordinates. --decimal-places accepts 0–5, defaults to 3 when rounding is enabled, and cannot be supplied without that flag. Inspect the results before replacing files in your project. There is no --in-place option.

Using saved Styles 

Use an explicit .axstyle file, such as a library exported from the Styles panel. The CLI neither searches your managed Styles folder nor imports, edits or saves the supplied library. Its maximum size is 4 MiB. It is parsed as inert, allowlisted Axialis XML, not executable WPF/Avalonia XAML.

First find the exact style key, then inspect the preset if needed:

IconVectorsCli.exe style list --library "team.axstyle" --format json
IconVectorsCli.exe style inspect --library "team.axstyle" --style-key primary --format json
IconVectorsCli.exe style apply --library "team.axstyle" --style-key primary --input-dir "assets" --output-dir "dist/styled" --dry-run --format json
IconVectorsCli.exe style apply --library "team.axstyle" --style-key primary --input-dir "assets" --output-dir "dist/styled" --format json

--style-key is the library’s exact, case-sensitive style key, not its display name. Replace primary with a key returned by style list. Keys contain 1–96 ASCII letters, digits, underscores or hyphens.

Read-only listing and inspection take no SVG input or asset destination. They may use --format and an explicit JSON --report like other commands.

style apply accepts --mode complete|fill|stroke:

complete is the default. It applies the saved supported appearance, including element opacity, both paints and stroke geometry.
fill applies fill paint, fill opacity and fill rule, leaving element opacity and stroke properties unchanged.
stroke applies stroke paint, stroke opacity, width, dashes, cap, join and miter limit, leaving element opacity and fill properties unchanged.

The modes share the panel’s paint/context semantics. Supported gradients travel with the style and receive nonconflicting resource IDs. Object-bounding-box gradients follow the target; user-space gradients retain their coordinates. A saved authored color context is applied when needed. A partial mode is rejected if changing that context would alter the untouched channel’s currentColor appearance, including gradient stops. It is not silently converted to a fixed color.

By default, application targets all eligible artwork. Use –id to select specific elements or a group’s drawable children:

IconVectorsCli.exe style apply --library "team.axstyle" --style-key primary --mode stroke --id badge --input "assets/app.svg" --output "dist/app.svg"

Styling preserves geometry and group transforms/compositing. Unsupported effects, gradients or ambiguous source mappings produce diagnostics rather than an incomplete appearance. The source SVG and library remain unchanged; previously generated SVGs are independent snapshots, not live-linked presets. The source-preserving style adapter supports a conservative subset of SVG and simple CSS selectors. It does not expand use instances or process nested SVG, external resources, active content, !important or unsupported effects. Stylesheet checks include all text and CDATA segments, not just the first segment. XML comments or nested elements inside an actual style element are rejected; use plain CSS text or CDATA there instead. Ordinary SVG comments outside the stylesheet are preserved. Keep the original and follow the reported diagnostic instead of assuming arbitrary SVG can be restyled losslessly.

Centering, fitting, rotating and flipping 

These commands transform the complete icon, preserving relative artwork positions and the existing canvas dimensions/viewBox. They share the Explorer’s Center and Fit and Rotate / Flip geometry behavior. They do not accept --id.

IconVectorsCli.exe transform center --input-dir "assets" --output-dir "dist/centered" --format json
IconVectorsCli.exe transform fit --input-dir "assets" --margin 1 --output-dir "dist/fitted" --dry-run --format json
IconVectorsCli.exe transform rotate --input "assets/arrow.svg" --angle -22.5 --output "dist/arrow.svg" --format json
IconVectorsCli.exe transform flip --input-dir "assets" --axis horizontal --output-dir "dist/flipped" --format json

center translates artwork without scaling. Centering is geometric, not optical. fit scales artwork and strokes proportionally inside equal margins; --margin defaults to zero and must be nonnegative, in SVG units. Supported stroke bounds are included. Conservative bounds can leave extra visible space; a margin must leave usable room inside each canvas.

rotate requires a finite signed --angle in degrees. Positive angles rotate clockwise about the existing canvas center; negative angles rotate counterclockwise. flip requires --axis horizontal|vertical and reflects about that center. Neither expands the canvas. Rotation, particularly on a non-square canvas or by an arbitrary angle, can move artwork outside it. Review clipping diagnostics and inspect the generated SVGs.

These commands do not change the canvas dimensions; use resize when you need a different canvas. No optical-centering command is included. Supported geometry/content limits remain the shared operation’s own limits; unsupported artwork is diagnosed, not flattened or stripped without permission.

Resizing to a new canvas 

resize requires integer --width and --height values, each from 8 to 1024 SVG units. It acts on the whole icon and does not accept --id.

IconVectorsCli.exe resize --input "assets/app.svg" --width 32 --height 32 --output "dist/app.svg" --dry-run --format json
IconVectorsCli.exe resize --input-dir "assets" --width 48 --height 32 --output-dir "dist/resized" --format json

The source canvas, not the painted artwork’s bounds, is scaled uniformly to fit inside the requested canvas and centered there. Original relative positions and canvas padding remain; a different aspect ratio leaves space on one axis instead of stretching the shapes. Artwork and strokes scale together. Nonzero source viewBox origins are included in the translation. For a changed result, width/height become the requested dimensions and the viewBox becomes 0 0 width height. A semantic no-op preserves original bytes.

This differs from the existing Editor/Explorer Resize operation, which can stretch artwork when the requested canvas aspect ratio changes. It does not change that operation’s behavior. Use transform fit to fit the painted artwork inside margins on an unchanged canvas instead. Unsupported geometry or paints are diagnosed rather than silently removed. Read any clipping findings and inspect the generated copy. Viewport-dependent user-space gradient coordinates can require a resize_unsupported diagnostic when the canvas extent changes; use explicit numeric gradient coordinates rather than silently changing their appearance.

Converting strokes to filled outlines 

outline-strokes converts supported visible strokes into filled vector geometry, using the same operation as Explorer Outline Strokes. It uses each stroke’s existing width, dashes, caps, joins and opacity, not a new set of appearance defaults. This is stroke outlining, not tracing a filled shape into a centerline.

IconVectorsCli.exe outline-strokes --input "icons/arrow.svg" --output "dist/arrow.svg"
IconVectorsCli.exe outline-strokes --input-dir "icons" --recursive --output-dir "dist/outlined" --dry-run --format json
IconVectorsCli.exe outline-strokes --input-dir "icons" --recursive --output-dir "dist/outlined" --format json
IconVectorsCli.exe command describe icon.outline-strokes --format json

The command acts on the whole icon. It accepts the common input, destination, overwrite, dry-run, result-format and report options; it has no --id targeting or width/color/cap/join tuning options. Output SVGs retain the source basename and relative folder structure under --output-dir; choose a distinct destination. Existing local product rights are required, including for dry-run. Neither the source files nor an open Editor document are changed.

A stroke-only shape is replaced directly with one filled outline path, retaining its identity and placement; no invisible original or unnecessary wrapper group is added. A shape with a visible fill retains that fill and the outline in the shared operation’s paint-order/compositing structure. Canvas, supported transforms, opacity and unrelated comments, metadata, resources and source bytes are preserved. Hidden/nonpainting strokes are not made visible; a semantic no-op returns the original bytes in its output copy.

The shared supported-content rules are conservative. Solid and symbolic currentColor strokes are supported; gradient/pattern strokes, rendered stylesheets, use references, text/images, nested viewports, filters, masks/clipping, markers, non-scaling strokes and other unsupported mappings are diagnosed rather than guessed or partly converted. Supported inline and inherited properties remain eligible. Read the diagnostic for unsupported dashes or degenerate geometry. One rejected input blocks the complete copy job; it is not silently skipped while the other files are written.

Before the shared path parser runs, the CLI limits every d or points attribute to 256 KiB, and their total to 2 MiB, excluding inert metadata subtrees only. This includes misplaced geometry attributes on groups, titles and descriptions: the shared validator parses those even though the renderer does not paint them. The limit is checked on the initial source snapshot and again on each actual reopened source before transformation. cli.outline.source_limit means the authored data exceeds this processing budget, not necessarily that the SVG syntax is invalid. The shared outlining engine also bounds elements, nesting, curves, dashes and intersection work. These limits do not change the Editor/MCP operation.

Shared outline_* findings appear in ordinary CLI diagnostics. The same copy-job, report and recovery safeguards apply, including truthful output counts on failure. Preserved metadata is not sanitized for use in other SVG consumers.

Changing colors and existing strokes 

IconVectorsCli.exe color replace --input-dir "assets" --from "#FF0000" --to "#0066FF" --target fill --output-dir "dist/recolored" --format json
IconVectorsCli.exe color replace --input "assets/app.svg" --from currentColor --to "#383838" --target both --output "dist/app.svg"
IconVectorsCli.exe color current-color --input-dir "assets" --target both --output-dir "dist/current-color" --dry-run --format json
IconVectorsCli.exe color current-color --input-dir "assets" --from "#383838" --target stroke --output-dir "dist/current-color"
IconVectorsCli.exe stroke --input-dir "assets" --width 2 --cap round --join round --color currentColor --output-dir "dist/strokes" --format json

color replace requires --from and --to, each an RGB in #RRGGBB format or the symbolic keyword currentColor. RGB matching uses the effective supported paint color, so equivalent authored spellings match; there is no tolerance or nearest-color mapping. currentColor matches the keyword itself, not its theme-resolved color or the SVG color property. Use --target fill|stroke|both to choose the channels; the default is both.

color current-color converts all eligible solid RGB paints by default. An optional --from "#RRGGBB" restricts conversion to that exact RGB. Both commands preserve effective paint alpha, separate opacities, and authored color context. They do not replace gradient stops, gradient/pattern references, filter colors or the color property. Conversion does not invent an absent stroke. Use the separate raster export --current-color option when you only need a rendering fallback without changing SVG paints.

stroke requires at least one change:

--width: a finite number from 0 to 1024 SVG units. Zero is nonpainting.
--cap butt|round|square: the endpoint shape.
--join miter|round|bevel: the corner shape.
--color "#RRGGBB" or --color currentColor: the existing stroke’s paint, preserving effective alpha.

Unspecified stroke properties remain unchanged. Changes affect effective existing strokes only, including supported inherited strokes; they do not add outlines to fill-only or stroke="none" artwork. The property values are absolute SVG units, not scaling factors.

Changing the color of an unsupported gradient stroke is rejected rather than silently replacing its resources. A supported gradient stroke can still receive width/cap/join changes when its color is left unchanged.

The paint commands share the source-preserving behavior of Explorer color batches: supported local values are edited where they control the result; inherited or shared CSS values can require local overrides. Geometry, comments, metadata and unrelated source bytes are retained. Unsupported CSS, effects or unsafe mappings reject the job intact rather than producing a partly recolored copy. A semantic no-op retains the original bytes in its output copy; it can still create a new file.

Applying an explicit palette 

palette apply requires --library pointing to an Axialis .axpal file. This is an inert AxialisPalette XML document, not an .axstyle Styles library. It is never imported into or read from your active panel state, and the supplied file is not modified.

IconVectorsCli.exe palette apply --library "team.axpal" --input-dir "assets" --output-dir "dist/palette" --dry-run --format json
IconVectorsCli.exe palette apply --library "team.axpal" --input-dir "assets" --output-dir "dist/palette" --format json

For example, a small palette file can contain:

<?xml version="1.0" encoding="utf-8"?>
<AxialisPalette>
  <Name>Team Colors</Name>
  <Swatch><Name>Accent</Name><Color>#2468AC</Color></Swatch>
  <Swatch><Name>Neutral</Name><Color>#383838</Color></Swatch>
  <Break/>
  <Swatch><Name>Background</Name><Color>#FFFFFF</Color></Swatch>
</AxialisPalette>

The file is limited to 4 MiB and 4,096 swatches and must contain at least one usable color. Breaks are separators, not colors. Invalid colors, unsafe XML, unsupported structure or exceeded parser limits reject the file; there is no implicit Adobe ACO conversion or managed-palette lookup.

Mapping uses the shared nearest-Lab color algorithm with normalized RGBA tie-breaking order. The chosen palette color’s alpha is adopted; do not assume the source paint’s alpha is preserved by this operation. Supported gradient stops and color attributes follow the shared rules. none, symbolic currentColor and resource URLs are not guessed as fixed RGBs. There is no --id selection or fill/stroke mask in this whole-icon command.

The original palette identity/content is frozen and protected through the job, just like a supplied style library. Source, output, report and hardlink aliases are rejected even with --overwrite; changing the palette while the job runs causes a conflict. The operation does not change panel settings, managed palettes or source SVGs. Unsupported SVG/CSS mappings reject intact. The JSON result’s palette object identifies its path, name, colorCount, byteSize and sha256 so a script can record exactly which palette was used.

Applying automatic gradients 

auto-gradient uses the existing Apply Auto Gradient operation to replace eligible paints with same-tone gradients. It acts on the complete icon and writes SVG copies, with no --id option or saved panel-state dependency.

IconVectorsCli.exe auto-gradient --input-dir "assets" --output-dir "dist/gradients" --dry-run --format json
IconVectorsCli.exe auto-gradient --input-dir "assets" --target both --type linear --angle 90 --force 15 --output-dir "dist/gradients"
IconVectorsCli.exe auto-gradient --input "assets/app.svg" --type radial --replace-existing-gradients --convert-current-color --current-color "#2468AC" --output "dist/app.svg" --format json

The defaults and allowed values are:

--target fill|stroke|both: default fill.
--type linear|radial: default linear.
--angle: integer 0–359 degrees, default 90; uses the shared Auto Gradient direction/position convention, including radial placement.
--force: integer 1–50, default 15; the shared gradient-strength setting.

Existing gradients and symbolic currentColor are preserved by default. --replace-existing-gradients opts into replacing supported local gradients using the shared base-color policy; their original shape and stop-opacity variation are not retained as an unchanged gradient.

--convert-current-color additionally converts eligible symbolic paints. Its opaque conversion base is --current-color "#RRGGBB" or black when omitted. Supplying --current-color without the conversion flag is an argument error, even for black. This base replaces the symbolic paint and overrides authored color-context RGB while preserving authored alpha and separate opacity. Unlike raster export’s currentColor fallback, it is an explicit SVG appearance conversion, not merely a preview setting.

Unselected paint channels and unsupported/no-op content follow the shared operation’s rules. Generated gradient IDs are deterministic and nonconflicting within an SVG, not automatically unique across different files. Explicit replacement is not promised to be idempotent. Review the new copies rather than assuming a second replacement must be a no-op.

Targeting exact SVG element IDs 

style apply, color replace, color current-color and stroke accept repeated --id options, with at most 256 unique IDs. Without them, each operation targets all eligible artwork, not resource definitions or metadata. For example:

IconVectorsCli.exe color replace --input "assets/app.svg" --id foreground --id badge --from "#FF0000" --to "#0066FF" --output "dist/app.svg" --dry-run --format json

An ID matches its exact, case-sensitive decoded SVG value. It is not a CSS selector, substring, ordinal or visible name. Selecting a group includes its eligible drawable descendants; overlapping selections do not apply twice. Every requested ID must resolve unambiguously in every input. A missing or duplicate/ambiguous ID rejects that input and therefore the complete copy job; other files are not silently processed on their own. Choose a narrower input set if only some icons contain the requested target.

Each ID is limited to 1,024 UTF-8 bytes, and the combined selection to 32,768 UTF-8 bytes; repeated duplicate arguments and oversized selections are usage errors, not silently truncated lists.

Targeting does not authorize rewriting an unsupported element or changing unselected artwork indirectly through a shared resource. Read diagnostics when the requested operation cannot preserve those boundaries.

Dry runs, JSON and reports 

--dry-run is available for every asset-generating command. It validates and plans the job, listing intended outputs and findings without creating asset directories, assets or backups. It still requires existing product rights. It does not prove that the later filesystem commit will succeed. Running without it takes a fresh source/output snapshot and validates again.

--format text is the human-readable default. --format json writes one UTF-8 JSON result to stdout, including for failures. Diagnostic/log output does not become a banner mixed into that JSON. --type chooses the image format; --format chooses the terminal result format.

Results identify schemaVersion (1), apiVersion (1), cliVersion (2.20.0, for example), command, status, exitCode and dryRun. They include inputs, outputs, diagnostics and counts:

reviewed records reviewed inputs; changed remains zero because source files are never changed by v1.
created, replaced and written describe actual output outcomes, not merely requested files. Dry-run outputs are planned, not created.
planned counts planned artifacts; unchanged can describe an optimized or transformed source that still produces a new copy. warnings counts warning findings.
failed counts inputs with source-validation failures or planning errors attributable to those inputs. It is not a count of every job/output failure: an output transaction or report can fail with failed still zero. Always examine exitCode and diagnostics.

Use stable diagnostic codes and the process exit code in scripts, not a match against English explanation text. Outputs identify paths, types and requested sizes where applicable. Recovery failures disclose surviving committed paths and recovery information. make-versions outputs additionally identify version as hot, disabled or dark. Never assume a failed command created no files. Cancellation uses status: "cancelled". A separate transactionStatus can retain a transaction outcome such as rollback or rejection; it must not be mistaken for a successful job merely because cleanup succeeded.

Add --report "reports/icons.json" to write an atomic JSON report, regardless of the terminal format. The report’s parent folder must already exist; create it explicitly first. Existing reports also require --overwrite. A report cannot alias an input, input list, supplied style or palette library, or generated asset. Dry runs may write this explicitly requested report, but no assets.

A report is not guaranteed for invalid arguments, denied entitlement or an unsafe input/destination rejected before processing. The terminal result and exit code remain authoritative. If assets commit but the subsequent report write fails, the command returns exit code 11 and discloses the actual outputs; it does not claim those assets were rolled back. Keep stdout as well as the exit code when calling from an agent or build system.

Exit codes 

Stable CLI v1 exit codes
Code	Meaning
0	Completed successfully and the diagnostic threshold passed.
1	Check/policy threshold failed, including unsupported input content.
2	Invalid command or arguments.
3	Input/source resolution or reading failed.
4	Reserved for a future script failure; v1 has no scripting command.
5	Permission or required capability denied.
6	Existing local product entitlement unavailable.
7	Collision, protected source/output alias or changed/stale file state.
8	Cancelled; inspect the reported filesystem outcome.
10	Internal failure.
11	Output/report I/O or transaction recovery failure.

Every failure is nonzero, including partial output. Consult diagnostics and outputs as well as the code; a recovery error is not equivalent to a cleanly cancelled job.

When a phase collects multiple error conditions, the aggregate exit priority is 11, 10, 8, 7, 6, 5, 3, 2, 1, highest first. Argument/input-resolution phases can stop before later phases run; this priority does not imply that the CLI executes unsafe or unauthorized work just to collect additional errors.

Safety and limits 

The CLI freezes bounded source snapshots, validates explicit destinations, stages the whole output job and rechecks file state before committing. It shares the application’s staged output/recovery machinery, not Editor Undo. Do not depend on Undo to remove CLI-generated files.

Symlink/reparse traversal, duplicate physical inputs, unsafe path components, input/output aliases are rejected. Export/check also reject external SVG resources; inspection can report their unsupported-content warning without rendering them. --overwrite authorizes replacement of validated outputs only; it does not relax those checks. Supported inert legacy SVG DOCTYPE declarations are handled without fetching an external DTD. Never remove security checks to make an unknown SVG pass; inspect the diagnostic and repair the source instead.

A job is limited to 4,096 SVG inputs, 16 MiB per input and 128 MiB total input bytes, and 8,192 generated artifacts. Encoded output limits are 64 MiB per artifact and 256 MiB per job. Directory discovery and SVG syntax/complexity also have bounds; a limit failure is an error, not silently truncated work. For style application, aggregate CSS limits are 4,096 simple selector instances, 32,768 declarations, 32 MiB of expanded rule text and 2,000,000 estimated selector/declaration visits across the artwork. These are checked before entering the renderer. styles.source_limit means the supported processing budget was exceeded, not necessarily that the SVG syntax is invalid. An explicit style or palette library is additionally bounded to 4 MiB and its original identity/content is protected and rechecked during the job. Changing it while a job is being planned or committed causes a conflict, not an unannounced switch to a different preset. Asset/report paths may never replace it, even with --overwrite. No command changes managed Styles/palette storage or remembers new panel/batch settings. Before entering the renderer, local use expansion is conservatively limited to 100,000 expanded nodes, 512 expanded nesting levels and 64 reference levels, with cycles rejected. Both href and xlink:href contribute to that budget; a tiny XML file is not assumed to have tiny rendering cost.

These operations are not an SVG sanitizer. Unrelated metadata and source content are preserved; content treated as inert by the pinned renderer is not automatically certified safe for another application or execution environment.

Repeatability depends on the same input bytes, options, CLI and renderer dependencies. Sorted discovery and locale-independent reports do not imply byte-identical raster files across different platforms or dependency versions.