Messagevisor

Command Line Interface (CLI)

The Messagevisor CLI is the main authoring and operations surface for a project. It covers project setup, validation, examples, evaluation, building, testing, catalog workflows, CSV exchange, and sets-based promotion flows.

This page is the command reference for the CLI as exposed from packages/core. Use it as the practical map, then follow the related links for deeper model-specific details.

Before you start

The CLI expects to run inside a Messagevisor project directory or a child directory of one.

Typical invocation:

Command
$ npx messagevisor <command> [options]

If your project uses sets, some commands require --set=<name> so Messagevisor knows which definition tree to operate on.

Output modes

Many commands support one or more of these output styles:

  • plain text: optimized for humans in a terminal
  • --json: machine-readable output
  • --pretty: pretty-print JSON output
  • --verbose: more detail for debugging

When a command supports JSON output, prefer it for scripts and CI checks.

Typical authoring loop

Command
$ npx messagevisor lint
$ npx messagevisor test
$ npx messagevisor build

Add these as needed:

  • examples when you want to inspect authored examples
  • evaluate when you want to debug a single message, raw string, or segment
  • catalog when you want a browsable project view

init

Create a new project starter.

Use this when:

  • bootstrapping a new repo
  • creating a scratch project to try a workflow
  • comparing YAML and JSON project layouts

Examples:

Command
$ npx messagevisor init
$ npx messagevisor init --project=json
$ npx messagevisor init --project=environments

Notes:

  • run init from an empty project directory for the cleanest setup
  • if the current directory is not empty, init prompts for a new child directory name and initializes the starter there
  • pass --overwrite to initialize in the current directory anyway; existing conflicting files are skipped, not replaced
  • --project selects a starter shape
  • the generated project is only a starting point; you will usually tailor directories, config, and modules right away

Read next:

config

Print the resolved project configuration.

Use this when:

  • confirming which parser is active
  • checking resolved directory paths
  • verifying sets/modules/export options

Examples:

Command
$ npx messagevisor config
$ npx messagevisor config --json --pretty

Notes:

  • this shows resolved configuration, not just the literal contents of messagevisor.config.js
  • it is often the fastest way to confirm whether a path override or module registration is being picked up

Read next:

info

Show a quick entity-count summary for the current project.

Use this when:

  • sanity-checking a project after import or promotion
  • getting a quick overview before a review or debugging session

Example:

Command
$ npx messagevisor info

Read next:

lint

Validate project definitions.

Use this when:

  • checking schema correctness
  • catching missing references and invalid format shapes
  • validating tests before running them

Examples:

Command
$ npx messagevisor lint
$ npx messagevisor lint --json --pretty
$ npx messagevisor lint --set=staging

Behavior notes:

  • lint validates authoring definitions, not runtime output
  • for sets-based projects, lint can cover all sets or a single set depending on how you invoke it
  • if you are changing locale format presets, target filters, or test assertion shapes, lint is usually the first command that tells you whether the structure is valid

Read next:

list

List one class of entity at a time.

Supported entity switches:

  • --messages
  • --locales
  • --segments
  • --attributes
  • --targets

Examples:

Command
$ npx messagevisor list --messages
$ npx messagevisor list --messages --target=web
$ npx messagevisor list --locales
$ npx messagevisor list --targets

Common filters:

  • --keyPattern=<regex>
  • --description=<regex>
  • --withTests
  • --withoutTests
  • --archived=true|false
  • --promotable=true|false

Target-aware behavior:

  • list --messages --target=<target> filters messages by the target's includeMessages and excludeMessages
  • when multiple targets are provided, the result is the union of messages included by those targets

Edge cases:

  • pass exactly one of --messages, --locales, --segments, --attributes, or --targets
  • --withTests and --withoutTests are not supported for attributes

Read next:

find-duplicates

Find active message keys that resolve to the same translation value.

Use this when:

  • reviewing copy reuse before cleanup
  • finding accidental duplicate labels across namespaces
  • auditing inherited regional translations

Examples:

Command
$ npx messagevisor find-duplicates
$ npx messagevisor find-duplicates --locale=en-US
$ npx messagevisor find-duplicates --set=staging
$ npx messagevisor find-duplicates --locale=en-US --json --pretty

Behavior notes:

  • duplicate groups are scoped by locale
  • locale translation inheritance is applied before comparing values
  • overrides are ignored
  • archived messages and empty translation values are ignored
  • in sets-based projects, the command scans all sets independently unless --set=<set> is passed

Read next:

create

Scaffold entities from the CLI.

Use this when:

  • creating many messages quickly
  • generating empty locale or segment files to fill in later
  • reducing repetitive path creation during authoring

Typical example:

Command
$ npx messagevisor create --messages --keys=$'auth.signin\nauth.signout'

Notes:

  • this is a convenience authoring command, not a migration framework
  • it is most useful for generating the initial file structure, then editing the authored content yourself

Read next:

examples

Resolve and print authored examples from locales and messages.

Use this when:

  • previewing example output without building an app
  • checking matrix-expanded examples
  • verifying that locale inheritance, target formats, and module behavior are producing the intended results

Examples:

Command
$ npx messagevisor examples
$ npx messagevisor examples --locale=en-US
$ npx messagevisor examples --exampleIndex=2 --matrixIndex=3
$ npx messagevisor examples --descriptionPattern=welcome --translationPattern=adult
$ npx messagevisor examples --onlyMessages
$ npx messagevisor examples --onlyLocales
$ npx messagevisor examples --json --pretty

Important behaviors:

  • examples covers both locale examples and message examples
  • --onlyMessages and --onlyLocales narrow the output to one class
  • --locale=<locale> filters to one locale
  • --exampleIndex and --matrixIndex are 1-based filters for already-authored example numbering
  • values that look like ISO date strings are coerced into Date objects before evaluation so authored examples can drive date/time formatting cleanly
  • the same message and locale examples are also available in the generated Catalog, which is better for browsing and stakeholder review

Read next:

evaluate

Evaluate one thing directly from the CLI. This is the fastest debugging command in the toolchain.

There are three modes:

  • --message=<key>: resolve an existing message key through a built target+locale datafile
  • --rawMessage=<string>: evaluate an inline message string through the runtime modules for a locale
  • --segment=<key>: evaluate a segment against context

Examples:

Command
$ npx messagevisor evaluate --message=auth.signin --locale=en-US
$ npx messagevisor evaluate --message=dashboard.welcome --locale=en-US --values='{"name":"Ada"}'
$ npx messagevisor evaluate --rawMessage="Hello {name}" --locale=en-US --values='{"name":"Ada"}'
$ npx messagevisor evaluate --segment=platform-web --context='{"platform":"web"}'

How the modes differ:

  • --message uses the real built datafile path for the selected target and locale
  • --rawMessage skips message lookup and formats the literal string through registered modules
  • --segment does not need --locale; it only needs segment definitions plus context

Common options:

  • --target=<target>
  • --locale=<locale>
  • --values=<json>
  • --context=<json>
  • --set=<set>
  • --json
  • --pretty

Edge cases:

  • pass either --message or --rawMessage, not both
  • --message and --rawMessage require --locale
  • --segment works without --locale
  • malformed JSON in --values or --context fails early

Read next:

benchmark

Benchmark translation evaluation against a built target+locale datafile.

Use this when:

  • comparing target sizes or override complexity
  • measuring hot-path translation performance
  • checking the effect of modules or context-heavy messages

Typical usage:

Command
$ npx messagevisor benchmark --message=auth.signin --target=web --locale=en-US -n=1000

Behavior notes:

  • benchmark numbers are only meaningful when you keep target, locale, values, and modules stable between runs
  • if you care about app startup cost too, combine this with build output inspection and catalog inspection

Read next:

build

Generate runtime JSON datafiles.

Use this when:

  • publishing translations for applications
  • inspecting the exact target-filtered output the SDK will consume
  • validating target-level format overrides and included-message sets

Examples:

Command
$ npx messagevisor build
$ npx messagevisor build --target=web --locale=en-US
$ npx messagevisor build --set=production
$ npx messagevisor build --showSize

What build does:

  • resolves locale format inheritance
  • applies target-level locale format overrides
  • filters messages by target inclusion/exclusion rules
  • includes only the attributes and segments needed by included overrides
  • writes one datafile per target and locale combination

Key options:

  • --target=<target>
  • --locale=<locale>
  • --set=<set>
  • --showSize
  • --json
  • --pretty
  • --noStateFiles

Edge cases:

  • in sets mode, some invocations require --set
  • building a single target/locale pair is often the easiest way to debug a target-specific issue
  • target context influences which overrides survive the build
  • target files control datafile serialization with pretty, stringify, and revisionFromHash

Read next:

test

Run Messagevisor project tests.

Supported test subjects:

  • messages
  • segments
  • locales
  • targets

Examples:

Command
$ npx messagevisor test
$ npx messagevisor test --keyPattern=welcome
$ npx messagevisor test --assertionPattern=evaluation
$ npx messagevisor test --onlyFailures
$ npx messagevisor test --showDatafile
$ npx messagevisor test --verbose
$ npx messagevisor test --json --pretty

What tests can do:

  • message assertions evaluate resolved translations
  • segment assertions verify segment matching against context
  • locale assertions can verify resolved formats and evaluate rawMessage
  • target assertions can verify included/excluded messages, resolved formats, and evaluate either rawMessage or message

Helpful filters:

  • --keyPattern=<regex> narrows the test file set
  • --assertionPattern=<regex> narrows individual assertions by description
  • --onlyFailures keeps output short when you already know the suite is noisy
  • --showDatafile is especially useful for target assertions

Behavior notes:

  • matrix-expanded assertions are filtered after description expansion
  • key-like fields stay literal in matrix expansion unless the assertion type explicitly supports placeholders there
  • target assertion evaluation uses the actual built target datafile, so missing translations follow normal SDK behavior instead of producing a custom test-only error

Read next:

export

Export translations to CSV.

Use this when:

  • preparing files for translators
  • reviewing translation status outside the repo
  • exchanging direct and inherited translations in a spreadsheet workflow

Examples:

Command
$ npx messagevisor export
$ npx messagevisor export --locale=en-US --target=web
$ npx messagevisor export --locale=en --locale=nl-NL --target=web
$ npx messagevisor export --print

Useful options:

  • --locale=<locale>; omit it for all locales, or repeat it for multiple locale columns
  • --target=<target>
  • --includeMessages=<pattern>
  • --excludeMessages=<pattern>
  • --excludeOverrides
  • --withoutDescription
  • --withoutStatus
  • --onlyUntranslated
  • --onlyDirectlyUntranslated
  • --print
  • --output=<path>
  • --force
  • --delimiter=<char>
  • --bom
  • --lineEnding=lf|crlf

Behavior notes:

  • export status distinguishes direct, inherited, and missing translations
  • repeated --locale is useful for source/reference plus target handoff files
  • target filters apply before rows are emitted
  • --print writes the CSV to stdout instead of creating a file

Read next:

import

Import translations from CSV, or from a flat JSON object with --from-json.

Use this when:

  • round-tripping a Messagevisor export through external translation work
  • applying translated cells back into message and override translation maps
  • previewing CSV changes before writing files
  • pulling already available JSON translations into one locale

Examples:

Command
$ npx messagevisor import exports/messagevisor-export-20260419T123456.csv
$ npx messagevisor import --input=translator/nl.csv --apply
$ npx messagevisor import --input=translator/nl.csv --locale=nl-NL --apply
$ npx messagevisor import --input=translator/en-US.csv --locale=en-US --prune --apply
$ npx messagevisor import translations.csv --set=staging
$ npx messagevisor import translations.json --from-json --locale=nl-NL
$ npx messagevisor import https://example.com/nl-NL.json --from-json --locale=nl-NL --apply
$ npx messagevisor import payload.json --from-json --json-path=data.translations --locale=nl-NL

Useful options:

  • --input=<path>
  • --set=<set>
  • --locale=<locale>
  • --createMissing
  • --apply
  • --prune
  • --from-json
  • --json-path=<path>
  • --delimiter=<char>
  • --bom

Behavior notes:

  • import expects the export-style CSV shape
  • without --locale, import reads all known locale columns in the CSV
  • repeat --locale to import only selected locale columns
  • --from-json expects one flat object of messageKey: translation pairs and exactly one --locale
  • --json-path selects a nested object using dot-path syntax, such as data.translations
  • import previews changes by default and does not write files
  • --apply writes imported translations to message files
  • --prune skips or removes direct translations when the imported value matches inherited copy
  • --createMissing allows message creation when the import references unknown keys
  • override rows are mapped using the configured exportOverrideKeySeparator
  • in sets projects, JSON import requires exactly one --set=<set>

Read next:

generate-code

Generate typed runtime helpers from your project.

Use this when:

  • you want generated message key types or helpers
  • you want a React-oriented codegen shape for app integration

Examples:

Command
$ npx messagevisor generate-code --language typescript --out-dir src/generated
$ npx messagevisor generate-code --language typescript --out-dir src/generated --react

Behavior notes:

  • generated output depends on your current project definitions
  • code generation complements the SDK; it does not replace datafile building

Read next:

prune

Remove stale authoring data.

Use this when:

  • cleaning unused translations
  • removing dead format presets
  • narrowing a project after target or locale changes

Examples:

Command
$ npx messagevisor prune --translations
$ npx messagevisor prune --translations --target=web --apply
$ npx messagevisor prune --formats --locale=en-US

Behavior notes:

  • prune commands are intentionally selective; preview first, then apply
  • target-aware pruning lets you ask "what is unused for this target?" rather than only "what is unused globally?"

Read next:

promote

Copy authoring changes from one set to another.

Use this when:

  • moving definitions through dev -> staging -> production
  • reviewing whether one set can be promoted cleanly
  • producing an audit trail for sets-based change movement

Examples:

Command
$ npx messagevisor promote --from=dev --to=staging
$ npx messagevisor promote --from=dev --to=staging --target=web
$ npx messagevisor promote --from=dev --to=staging --excludeOverrides
$ npx messagevisor promote --from=dev --to=staging --conflicts=fail
$ npx messagevisor promote --from=dev --to=staging --showUnchanged
$ npx messagevisor promote --from=dev --to=staging --apply
$ npx messagevisor promote --from=dev --to=staging --apply --audit=markdown

Useful options:

  • --from=<set>
  • --to=<set>
  • --target=<target>
  • --locale=<locale>
  • --includeMessages=<pattern>
  • --excludeMessages=<pattern>
  • --excludeOverrides
  • --conflicts=source|destination|fail
  • --allowEmpty
  • --apply
  • --audit=json|markdown
  • --showUnchanged

Behavior notes:

  • promote previews changes by default and does not write files
  • --apply writes the promotion to the destination set
  • --audit writes an audit file only when used with --apply
  • conflict handling is explicit because promotions can merge arrays and object structures, not just copy whole files
  • projects can restrict allowed flows via promotionFlows

Read next:

catalog

Work with the generated project catalog.

Main entry points:

  • catalog: combined export + serve + watch flow
  • catalog export: generate static catalog files
  • catalog serve: serve the generated catalog locally

Examples:

Command
$ npx messagevisor catalog
$ npx messagevisor catalog export
$ npx messagevisor catalog serve
$ npx messagevisor catalog export --hashRouter
$ npx messagevisor catalog serve --hashRouter

Routing behavior:

  • browser router is the default
  • that means generated URLs are clean and do not include #
  • use --hashRouter only when your host cannot fall back to index.html for deep routes

Read next:

Troubleshooting patterns

A translation looks wrong

  1. Run evaluate --message=... --target=... --locale=...
  2. If the result depends on conditions, add --context=...
  3. If the message uses formatting or ICU syntax, confirm your project modules in config
  4. If the message is target-specific, build that target+locale pair and inspect the datafile or catalog

A segment does not match the way you expect

  1. Run evaluate --segment=... --context=...
  2. Check the attribute schema and condition operators
  3. If the segment is only used in overrides, build or test the affected message/target path too

A target seems to be missing a message

  1. Run list --messages --target=<target>
  2. Run test --keyPattern=<target-or-message>
  3. Build the target+locale pair and inspect the resulting datafile
  4. If you are using sets, make sure you are looking at the right --set

An example or locale test is formatting differently than expected

  1. Confirm locale format inheritance in Locales
  2. Check target-level format overrides in Targets
  3. Confirm runtime modules in Modules
  4. Re-run with examples, evaluate, or test --showDatafile depending on whether you are debugging authoring examples, raw runtime behavior, or built output

Workflow recipes

Validate a project before publishing datafiles

Command
$ npx messagevisor lint
$ npx messagevisor test
$ npx messagevisor build --showSize

Debug a raw ICU string for one locale

Command
$ npx messagevisor evaluate --rawMessage="{count, plural, one {# item} other {# items}}" --locale=en-US --values='{"count":2}'

Inspect only locale examples

Command
$ npx messagevisor examples --onlyLocales --locale=en-US --json --pretty

Review a target-specific issue

Command
$ npx messagevisor list --messages --target=web
$ npx messagevisor test --keyPattern=web --showDatafile
$ npx messagevisor build --target=web --locale=en-US

Generate and browse the catalog locally

Command
$ npx messagevisor catalog