cirup

cirup is a command-line tool for working with localization resource files. It supports .json, .resx, and .restext files.

Quick start

Install cirup globally as a .NET tool:

dotnet tool install -g Devolutions.Cirup.Tool

Build the workspace:

cargo build --workspace

Run help:

cargo run -p cirup_cli -- --help

Use an installed binary:

cirup --help

Global options

• --output-format <jsonl|json|table>: control stdout format. Default is jsonl.
• --dry-run: compute results without writing output files. If a command normally writes to a file, the result is rendered to stdout instead.
• --check: imply --dry-run and exit with code 2 when the command would produce changes.
• --summary: print a structured execution summary instead of full result rows. Combine it with --dry-run for inspect-only workflows.
• --count-only: print only the number of matching results to stdout.
• --key-filter <pattern>: keep only results whose key matches a simple regex-style pattern. Repeatable. Supported syntax: literals, ^, $, ., and .*.
• --value-filter <pattern>: keep only results whose value matches the same simple regex-style syntax. Repeatable.
• --limit <n>: keep only the first n matching results.
• --quiet: only print errors to stderr.
• --log-level <error|warn|info|debug|trace>: set stderr verbosity explicitly.
• -v, -vv, ...: increase log verbosity starting from the default warn level.
• -C, --show-changes: for file-diff, include keys that exist in both files but have different values.
• --touch: force writing output files even when generated bytes are identical.
• --output-encoding <utf8-no-bom|utf8-bom|utf8>: control output file encoding. utf8 behaves like utf8-no-bom.

By default, cirup writes JSONL to stdout, logs at warn level, and avoids rewriting output files when content has not changed.

--summary emits compact metadata such as counts, write intent, and whether output would be truncated. --check is intended for automation and returns exit code 2 when a command would produce changes.

--key-filter and --value-filter are intentionally limited to a SQL-translatable subset. Unsupported syntax such as |, (), [], {m,n}, +, and lookarounds is rejected instead of being interpreted as full regex.

Common operations

Print a file

cirup file-print input.resx

Show a human-readable table instead:

cirup --output-format table file-print input.resx

Write the printed content to a file:

cirup file-print input.resx output.json

Preview the same operation without writing the output file:

cirup --dry-run file-print input.resx output.json

Convert between formats

cirup file-convert input.resx output.json
cirup file-convert input.json output.restext

Sort keys

Sort in place:

cirup file-sort strings.json

Sort to a separate file:

cirup file-sort strings.json strings.sorted.json

Diff missing keys

Show keys present in file1 but missing in file2:

cirup file-diff file1.resx file2.resx

Count missing keys without writing the full result set:

cirup --count-only file-diff file1.resx file2.resx

Ask only whether differences exist:

cirup --check file-diff file1.resx file2.resx

Write diff to file:

cirup file-diff file1.resx file2.resx diff.resx

Include value changes as well:

cirup --show-changes file-diff file1.resx file2.resx

Merge values

Merge values from file2 into file1:

cirup file-merge file1.resx file2.resx merged.resx

Intersect files

Keep only exact key/value pairs common to both files:

cirup file-intersect file1.json file2.json intersect.json

Subtract keys

Keep values from file1 whose keys are not in file2:

cirup file-subtract file1.restext file2.restext result.restext

Diff with base file

Show keys that are in new, not in old, and also present in base:

cirup diff-with-base old.resx new.resx base.resx

Limit stdout to a subset of keys:

cirup --key-filter ^lbl --limit 25 diff-with-base old.resx new.resx base.resx

Match keys containing a simple wildcard sequence:

cirup --key-filter 'User.*Name' file-print input.resx

Filter by translated value content:

cirup --value-filter '^Hello' file-print input.resx

Emit a structured summary for an in-place sort without modifying the file:

cirup --dry-run --summary file-sort strings.json

Output file touch behavior

• Default: if output bytes are unchanged, cirup does not rewrite the file.
• With --touch: cirup always rewrites output files.

Examples:

cirup file-sort strings.resx
cirup --touch file-sort strings.resx

NuGet package usage (.NET)

The Devolutions.Cirup.Build package can run cirup operations during MSBuild.

Example project setup:

<ItemGroup>
  <PackageReference Include="Devolutions.Cirup.Build" Version="1.2.3" PrivateAssets="all" />
  <CirupResources Include="Properties\Resources.resx" />
  <CirupResources Include="Properties\Resources.fr.resx" />
</ItemGroup>

Run local end-to-end validation:

pwsh ./nuget/test-e2e.ps1

Dotnet tool usage (.NET 10+)

cirup is also available as a RID-specific dotnet tool package: Devolutions.Cirup.Tool.

Install globally:

dotnet tool install -g Devolutions.Cirup.Tool
cirup --help

Run one-shot without permanent install:

dotnet tool exec Devolutions.Cirup.Tool -- --help
dnx Devolutions.Cirup.Tool --help

Create local dotnet tool packages from prebuilt release artifacts:

pwsh ./nuget/pack-cirup-dotnet-tool.ps1 -Version 1.2.3 -ArtifactsRoot ./dist -OutputDir ./dist/nuget

Quality checks

cargo test --workspace
cargo fmt --all --check
cargo clippy --workspace --all-targets