part_of = id:dx4hxn744/kv2bv2m
title = fig
version = 6.0.0
author = adammharris
created = 2026-05-08
updated = 2026-10-14T21:00:00-06:00
contents = [[fig docs](docs/docs.md), [Fig Banner Dark](/assets/fig-banner-dark.svg.yaml), [Fig Banner](/assets/fig-banner.svg.yaml), [fig on diaryx.org](/www/index.md), [Audiences](/vocab/audiences.md), [Languages](/languages/README.md)]
config = .config/prov.yaml
registry = registry.yaml
id = b9j9zgk
slug = fig
fig edits config files losslessly: make an edit and every comment, blank line, quote and key order remains untouched. It converts between formats retaining as much as possible, including comments, and reports exactly what is dropped if a format doesn't support something.
fig's command-line tool has ten formats built in. The underlying library is maintained for Rust,
TypeScript, Zig and C and has no languages built in. Every language is registered the same way, and a kit is included to make it easy to write your own in any of those languages.
The CLI
Take a messy YAML file:
# config.yaml — Deploy settings
service:
name: api # must match the DNS record
replicas: 2
ports:
defaults:
retries: 3
timeout: 30s
worker:
<<: *defaults
replicas: 1
Change a value and annotate it:
service:
name: api # must match the DNS record
- replicas: 2
+ replicas: 5 # bumped for Black Friday
ports: [80, 443]
One line changed.
Read through YAML's anchors and merge keys:
{
}
Convert to another format, and keep the comments:
{
}
Merge one file into another, or one part of one file into part of another, touching nothing the patch doesn't name. The two files need not share a format:
# overlay.toml — the us-west rollout
# config.yaml — Deploy settings
&
Built-in formats
You can make your own formats with fig!
But these are the ones that are built-in:
| Format | Files | |
|---|---|---|
| YAML | .yaml, .yml |
1.2.2 and 1.1; anchors, aliases, merge keys |
| JSON | .json, .jsonc, .json5 |
strict, JSONC and JSON5 |
| TOML | .toml |
1.1 and 1.0, datetimes |
| ZON | .zon |
Zig Object Notation |
| NestedText | .nt |
https://nestedtext.org |
| Java properties | .properties |
|
| dotenv | .env |
|
| INI | .ini |
|
| Property list | .plist |
Apple's XML plist |
| figl | .figl |
fig's own authoring dialect |
Installation
Install it with Homebrew, download it from GitHub Releases, or run it with no install at all (Node 22+, see docs/npm-wasi.md):
Run fig help for a list of commands.
The library
The CLI is a thin layer over the fig library.
use ;
let path = ;
let mut ed = open?;
ed.set_value?;
ed.set_trailing_comment?;
write?;
// serde_json-style, in any format you depend on
let cfg: Config = from_str?;
let toml = to_string?;
[]
= "6"
= "6" # one crate per format
= "6"
No Zig toolchain is needed for most platforms. serde is optional: fig
has its own #[derive(ToValue, FromValue)]. See Rust.
From TypeScript:
import { Editor, registerLanguage } from "@diaryx/fig";
import yaml from "@diaryx/fig-yaml";
using ed = Editor.open(src, registerLanguage(yaml));
ed.setValue(["service", "replicas"], 5);
ed.setTrailingComment(["service", "replicas"], "bumped for Black Friday");
See TypeScript, Zig, and for C,
bindings/c/include/fig.h.
Bring your own format
A 'language' simply tells fig:
- how to parse its text into a table of nodes,
- how to print one back,
- and how its syntax is spelled.
Bring your own comment markers, key–value separators,
and so forth, and fig will do everything else:
- comment-preserving edits: set, insert, delete, rename, move, reorder, comment out and back in
- conversion to and from every other registered format, comments included
diagnose,fig patch,fig getand every other CLI action- a check when it registers: fig parses, prints, reparses and edits its sample documents, and refuses a language that doesn't hold up
dotenv is the smallest language, for reference. Each built-in language package builds a C library, a WebAssembly module, a Rust crate and an npm package. See Languages.
A language can also be written in JavaScript, with @diaryx/fig/kit's node
table, tree, scanner and grammar combinators; in Rust, by implementing
fig::language::Language (see
Runtime languages); or as any program that
speaks the helper protocol, JSON-RPC over stdio.
Name a helper in a ~/.config/fig/languages.figl and every fig action accepts its
files, and fig lang check holds it to a built-in twin.
Why fig?
fig was originally created for Diaryx,
a project whose goal is preservation and readability. Existing tools
read one file in and write an often very different new file out,
because they prioritize simply getting information from one place to another
rather than preserving the file as it is.
toml_edit accomplishes this goal, but only for the TOML format.
fig generalizes its structure to an arbitrary number of formats.
In this way, it is a bit like serde but with editing support as well---serdedit, if you will.
fig ensures fidelity with lots of testing and daily fuzzing. The whole conformance suite is found at https://github.com/diaryx-org/fig-conformance.
Possible future features
- Styling directives that carry across formats (a TOML inline table as a YAML flow mapping)
- Structure-aware diff and three-way merge (
fig patchis the one-way half) fig fmt: sort keys, dedupe
Fine print
Contributions are welcome, subject to my approval.
License: MIT or Apache 2.0, at your option. If you use fig in your
work, I would love to hear from you and feature you here.
Credits: I am thankful for the toml_edit Rust crate, which guided the
structural edits a format-preserving TOML editor needs.
Contact me
adam@diaryx.org, or open an issue.