CLI Reference

CLI Reference

The lexicon executable is designed for scripts, editors, and automation. Commands either print structured JSON or emit TaskPaper output that can be redirected into files.

Validate and Lint

swift run lexicon validate commerce.lexicon
swift run lexicon validate commerce.lexicon --strict
swift run lexicon lint commerce.lexicon

Use validate for parse and reference diagnostics. Use lint or validate --strict when authoring warnings should fail a workflow.

Typical CI command:

swift run lexicon lint lexicons/commerce.lexicon

Inspect

swift run lexicon inspect commerce.lexicon
swift run lexicon inspect commerce.lexicon commerce.ui.product.card.buy.enabled

Without an ID, inspect prints document-level metadata: roots, imports, notes, comments, and diagnostics.

With an ID, it prints one resolved lemma: source, own type, resolved type, default value, notes, comments, own children, and resolved children.

Tree

swift run lexicon tree commerce.lexicon commerce --depth 4
swift run lexicon tree commerce.lexicon commerce --depth 4 --metadata
swift run lexicon tree commerce.lexicon commerce --depth 4 --inherited --metadata

Use tree without --inherited to see declared source structure. Add --inherited to see the live resolved structure, including inherited children from types.

Search

swift run lexicon search commerce.lexicon order submit --mode hybrid --limit 10
swift run lexicon search commerce.lexicon checkout button --mode token --limit 10
swift run lexicon search commerce.lexicon "customer asks for money back" --mode semantic

See Search for modes, scopes, MLX setup, and examples.

References

swift run lexicon refs commerce.lexicon commerce.ui.product.card.buy.enabled

refs prints outgoing and incoming type, synonym, and default references for one lemma. Use it when a rename looks risky or when you need to find every surface connected to a domain concept.

Excerpt

swift run lexicon excerpt commerce.lexicon commerce.ui.product.card

excerpt exports a branch as TaskPaper and reports reference diagnostics. It is useful when moving a subtree into its own file.

Format

swift run lexicon format commerce.lexicon
swift run lexicon format commerce.lexicon --check
swift run lexicon format commerce.lexicon --write
swift run lexicon format commerce.lexicon -o commerce.formatted.lexicon

By default, format prints canonical TaskPaper to stdout. Use --write to rewrite the input file.

Diff

swift run lexicon diff before.lexicon after.lexicon

diff reports added, removed, and changed nodes. It is more useful than a text diff when reviewers care about vocabulary effects rather than indentation noise.

Editing Commands

Editing commands print the updated document to stdout by default. Pass -o or --output to write another file.

swift run lexicon add commerce.lexicon commerce.ui.product.card badge \
	--type commerce.ui.type.label \
	--default '"New"' \
	-o commerce.next.lexicon

swift run lexicon rename commerce.lexicon commerce.ui.product.card.buy purchase \
	-o commerce.next.lexicon

swift run lexicon move commerce.lexicon commerce.ui.product.card.badge commerce.ui.product.summary \
	-o commerce.next.lexicon

swift run lexicon set-type commerce.lexicon commerce.ui.product.card.badge commerce.ui.type.label \
	-o commerce.next.lexicon

swift run lexicon unset-type commerce.lexicon commerce.ui.product.card.badge commerce.ui.type.label \
	-o commerce.next.lexicon

swift run lexicon set-protonym commerce.lexicon commerce.ui.product.card.buy.active enabled \
	-o commerce.next.lexicon

swift run lexicon set-default commerce.lexicon commerce.support.case.status '"open"' \
	-o commerce.next.lexicon

Notes and comments have subcommands:

swift run lexicon note add commerce.lexicon commerce.support.case.status "Displayed in the support queue."
swift run lexicon note remove commerce.lexicon commerce.support.case.status "Displayed in the support queue."
swift run lexicon note clear commerce.lexicon commerce.support.case.status

swift run lexicon comment add commerce.lexicon commerce.support.case.status "Keep aligned with Zendesk values."
swift run lexicon comment clear commerce.lexicon commerce.support.case.status

Interactive Session

swift run lexicon interactive commerce.lexicon
swift run lexicon repl commerce.lexicon --json

The REPL supports validation, tree views, search, refs, excerpts, edits, formatting, and save commands in one line-oriented session.

Example:

validate
tree commerce --depth 2 --metadata
add commerce.ui.checkout button
set-type commerce.ui.checkout.button commerce.ui.type.control
format
save
quit

Use --json when a tool or editor is driving the session.