lets transform

Structured edits for structured files: JSON, YAML, TOML and markdown frontmatter. Parses, mutates and re-emits, preserving comments, key order and indentation. Replaces jq, yq and sed run against config files.

lets transform [OPTIONS] [FILE]

What it does

--set, --delete and --append take a dotted path (a.b[0].c) and change one value in place without rewriting the rest of the file. The same structural guardrail that edit runs — a real parser for these four formats — runs before and after every change and reverts on failure.

Flags

Path syntax

• Dotted keys with numeric indexes: a.b[0].c.
• --set keeps the existing type. When path already holds a string, a numeric-looking value is still stored as a string; when it already holds a number or bool, the value is parsed as JSON. A brand-new key’s number is written byte-for-byte as typed (--set v=3.10 writes 3.10, not 3.1), since a version string and a decimal look identical on the command line.
• A quoted key is one literal key, not a path. --set '"editor.formatOnSave"=true' sets the single key literally named editor.formatOnSave, distinct from the nested path editor.formatOnSave.
• Attribute selectors — plugins[name=gitty].version — select the array element whose named field equals the given value. lets resolves the selector to a plain numeric index before any format-specific parser sees the path, and the footer names the resolution: plugins[name=gitty] → plugins[2]. No match is exit 1, listing the values the field actually held; more than one match is exit 2.
• --append 'bin[]={"name":"b","path":"b.rs"}' on a TOML array of tables appends a new [[bin]] table after the last one, keeping existing formatting.

Output shape

── <path> · <format> · <op summary> · line(s) <n>
<n>	<context line>
<n>~	<changed line>
<n>+	<inserted line>
<n>-	<deleted line>          (deleted)
── check: <format> ok · sha:<before>→<after>

Exit codes

Same table as edit (exit codes), plus this verb’s own reason for unsupported_file: a file that is not JSON, YAML, TOML or markdown-with-frontmatter, or a key that exists but can’t be changed in place (a tagged YAML node, or one reached through an alias).

Examples

Set two JSON values; comments and the rest of the file survive:

$ lets transform config.json --set features.e2e=false --set review.threads=3
── config.json · json · set features.e2e, review.threads · lines 3, 4
1   {
2     // feature flags
3~    "features": { "e2e": false },
4~    "review": { "threads": 3 }
5   }
── check: json ok · sha:bfe3e156b1ce→01c03fe96fd3 · ~21 tokens

Frontmatter is a YAML edit between the fences of a markdown file:

$ lets transform docs/note.md --set last_updated=2026.09.16
── docs/note.md · frontmatter · set last_updated · line 4
2 	title: Notes
3 	tags: [moc]
4~	last_updated: 2026.09.16
5 	---
6 	# Notes
── check: frontmatter ok · sha:5abff77ae5c2→60afc02190e6

An attribute selector that matches two elements is refused, not guessed:

$ lets transform compose.yaml --set 'services[name=web].image=c'
? 2
services[name=web].image is ambiguous (2 candidates)
  compose.yaml:2	services[0].name="web"
  compose.yaml:4	services[1].name="web"
ERROR_CODE=ambiguous

Append a TOML array-of-tables entry, formatting preserved:

$ lets transform Cargo.toml --append 'bin[]={"name":"b","path":"src/b.rs"}'
── Cargo.toml · toml · append bin · line 8
 5 	name = "a"
 6 	path = "src/a.rs"
 7+	
 8+	[[bin]]
 9+	name = "b"
10+	path = "src/b.rs"
── check: toml ok · sha:[..]→[..]

Deleting a key shows it struck out with a - marker, then the surrounding lines:

$ lets transform config/settings.yaml --delete legacy.token
── config/settings.yaml · yaml · delete legacy.token · line 4
1 	allow:
2 	  - ls
3~	legacy: {}
4-	  token: abc123 # remove me          (deleted)
── check: yaml ok · sha:8246dbee199f→72dd850c63b5

A YAML node that can’t be edited in place (it’s tagged) is refused rather than corrupted:

$ lets transform tags.yaml --append tags=wiki
? 7
tags.yaml is unsupported: tags cannot be changed in place (a tagged YAML node)
ERROR_CODE=unsupported_file