archmage export

The export subcommand parses configurations from spreadsheets and tree-structured data files, prunes each configuration tree, enforces validation rules, applies transformations, and emits the final output to the target directory.

See Data Export for the complete workflow.

Usage

archmage export -o <output-dir> [flags] <file1> [<file2> ...]

Input files may be specified as literal paths or glob patterns.

# Export a single spreadsheet to JSON
archmage export -o ./cooked item.xlsx

# Export all spreadsheets in a directory
archmage export -o ./cooked "configs/*.xlsx"

# Full pipeline with l10n, enums, and virtual tables
archmage export -o ./cooked \
  -e "enums/*.enum.yaml" \
  --l10n l10n.xlsx \
  --vtables-config virtual-tables.json \
  "configs/*.xlsx" "configs/*.yaml"

# Also export l10n as YAML and CSV
archmage export -o ./cooked \
  --l10n l10n.xlsx \
  --l10n-output-formats json,yaml,csv \
  "configs/*.xlsx" "configs/*.json"

Flags

Essential

--enum-files / -e

Comma-separated list of enum definition files or glob patterns. Required to resolve the enum types used in configurations.

archmage export -o ./cooked -e "enums/*.enum.yaml" item.xlsx

--format / -f

Output file format (default: json).

Valid values: json.

--l10n

Path to l10n.xlsx. Required when any input uses the l10n data type. l10n.xlsx contains all shared localizable strings to be reused across files.

During data export, Archmage collects all localizable strings from every input — l10n.xlsx, config files, and enum items. It then emits l10n.json, l10n.yaml, or l10n.csv, according to --l10n-output-formats, for downstream translation.

See the L10n Pipeline for details.

--output-dir / -o

The directory where output files are written.

--vtables-config

Path to the virtual table manifest, which defines multiple virtual tables.

A virtual table is a logical construct that groups similar regular tables, allowing Archmage to resolve them as a single unit during pipeline execution.

See Virtual Tables for details.

---

Filtering

These flags control which fields, config entries, tree nodes, and config sets reach the output.

See Filtering Mechanisms for more information.

--brace-flags / -b

Comma-separated brace flags for config set activation, evaluated against the Brace Flags embedded in field names.

--cflags

Comma-separated condition flags for config entry and tree node inclusion, evaluated against the cflags specified within conditions.

--semver

The config files’ semantic version (e.g., v1.0.0).

Archmage also writes it to the version.semver field in atlas.json.

See minver for more information.

--tags

Comma-separated general-purpose flags for field inclusion, evaluated against all tags from options and conditions.

--tags-xx

Comma-separated general-purpose flags for field exclusion, evaluated against all tags from options and conditions.

--xflags / -x

Comma-separated scenario flags for field inclusion, evaluated against all xflags from options and conditions.

---

Readability

Exported data shouldn’t feel like a puzzle. These flags put readability first — for humans and AI alike, by design.

--emit-anchors

Include config anchor strings in the output.

--emit-ids

Include the id field in each exported config entry. Only applies to regular tables.

--human-duration

Export durations as human-readable strings.

--human-enum

Export enum and bitflag values as readable strings instead of integers.

--human-ref

Export ref, backref, and backref-n values as readable strings when possible.

--human-wtpool

Export wtpool as an array of item-weight objects instead of parallel items and weights arrays.

--l10n-literal

Disable l10n aggregation and export l10n strings as-is.

--path-as-is

Preserve path values as-is (no dir stripping or ext replacement).

--readable

Enable all flags in this section at once, except --schema.

--schema

Generate a .schema file alongside each exported data file, describing its structure: one line per node, with the node’s path, data type, and description.

Only available when --format is json.

---

Data Type

--float-bit-size

The bit size for float types — 32 or 64 (default: 64).

--int-bit-size

The bit size for int and uint types — 32 or 64 (default: 64).

--tree-float-type

Default floating-point type for tree nodes (default: float64).

Valid values: float, float32, float64.

--tree-int-type

Default integer type for tree nodes (default: int64).

Valid values: int, int32, int64.

---

Others

--banner

Print the Archmage banner on startup.

--compact

Output JSON without indentation.

--crlf

Write all output files with CRLF (\r\n) line endings instead of LF (\n).

--cwd

Change the working directory before running. Relative paths are resolved from this directory.

--dotenv

Load environment variables from the specified file before running. If omitted and a .env file exists in the working directory, it’s loaded automatically.

--dry-run

Process all input files and validate them without writing any output.

--ext-map

Override output file extensions. Accepts key=value pairs (e.g., json=bin). Multiple pairs can be comma-separated.

archmage export -o ./cooked --ext-map json=bin "configs/*.xlsx"

--flush-on-progress

Flush logs immediately when progress updates.

--input-roots

Root directories for calculating relative paths for output files, comma-separated.

Input files may reside in any directory. They do not need to share a common parent, as long as their base names do not conflict.

Since all output files are written to a single output directory, you can use --input-roots to preserve the input directory structure:

archmage export --input-roots root1,root2 --output-dir out ...

For each input file, Archmage identifies the matching root and mirrors its relative path within the output directory.

--jq

Render node paths in error messages as jq expressions (.rewards[0].name) instead of JSONPath ($.rewards[0].name), ready to paste into a jq command.

--jq-schema

Render node paths in .schema files as jq expressions (.rewards[].name) instead of JSONPath ($.rewards.*.name).

--keep-orphaned

Keep existing output files not regenerated in this run. Archmage deletes them by default.

--l10n-output-formats

Output formats for gathered l10n strings (default: json).

Valid values: json, yaml, csv. Combine them with commas to emit several formats at once.

--no-atlas

Skip generating atlas.json.

--omit-zero

Drop fields with zero values.

Only the fields of objects and tuple are dropped. Map entries and array elements are kept, as dropping them would change a key set or shift positions.

An object is never dropped for being empty: {} indicates the object is present, whereas null does not.

--presence

Set the default presence for tree-structured data fields (default: implicit).

Valid values: implicit, optional, required.

For more information about how it works, see the presence option.

--skipped-log

Log skipped files and worksheets to the specified file.

--sort

Sort export data by config ID. Only applies to regular tables, including tree-backed regular tables.

--timezone

Default timezone for datetime values (default: UTC+00:00). Format: UTC+08:00, UTC-07:30.

--vcs

Collect version control information and embed it in atlas.json.

Value	Source
git	The Git repository in the current working directory
git@<dir>	The Git repository at <dir> (may be a subdirectory of the repo)
A file path	A custom JSON file describing the version

A custom JSON file takes this shape:

{
  "workspace": "",
  "tags": [],
  "branch": "main",
  "id": "7f3a2b9c8e1d4f6a5b2c9e8d7f3a2b9c8e1d4f6a",
  "shortId": "7f3a2b9",
  "timestamp": "2025-02-09T10:23:45Z",
  "message": "feat: add i18n support with language fallback",
  "author": "Alice Wang <[email protected]>",
  "status": [],
  "extra": {}
}

Examples:

archmage export -o ./cooked --vcs git configs/*.xlsx
archmage export -o ./cooked --vcs ./version.json configs/*.xlsx

--verbose / -v

Print extra status messages.

Environment Variables

Environment variables fine-tune output behavior for things that require cross-layer penetration — file naming, indentation style, and language-specific options.

Variable	Default	Description
ARCHMAGE_FILE_NAMING_STYLE	“”	Naming style for output files. Common values: snake, kebab, pascal, camel.
ARCHMAGE_INDENT_STYLE	“tab”	Indentation style: tab or space.
ARCHMAGE_INDENT_TAB_SIZE	4	Number of spaces per indent level when ARCHMAGE_INDENT_STYLE is space.