part_of = id:dx4hxn744/kv2bv2m
title = fig
version = 7.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 and C (and so any language with a C FFI, Zig among them) 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.
Take a messy YAML file:
# config.yaml — Deploy settings
service:
name: api # must match the DNS record
replicas: 2
ports: [80, 443]
defaults: &defaults
retries: 3
timeout: 30s
worker:
<<: *defaults
replicas: 1Change a value and annotate it:
$ fig set config.yaml service.replicas 5
$ fig comment --inline config.yaml service.replicas "bumped for Black Friday"@@ -2,5 +2,5 @@
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:
$ fig get config.yaml worker -o json
{
"replicas": 1,
"retries": 3,
"timeout": "30s"
}Convert to another format, and keep the comments:
$ fig get config.yaml service -o json5
{
name: "api", // must match the DNS record
replicas: 5, // bumped for Black Friday
ports: [
80,
443
]
}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:
$ cat overlay.toml
# overlay.toml — the us-west rollout
[service]
replicas = 8
region = "us-west"
$ fig patch config.yaml overlay.toml --diff
--- config.yaml
+++ config.yaml
@@ -1,8 +1,9 @@
# config.yaml — Deploy settings
service:
name: api # must match the DNS record
- replicas: 5 # bumped for Black Friday
+ replicas: 8 # bumped for Black Friday
ports: [80, 443]
+ region: us-west
defaults: &defaults
retries: 3You 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 |
Install it with Homebrew, download it from GitHub Releases, or run it with no install at all (Node 22+, see docs/npm-wasi.md):
brew install diaryx-org/tap/fig
npx @diaryx/fig-wasi get config.yamlRun fig help for a list of commands.
The CLI is a thin layer over the fig library.
use fig::{Editor, Segment};
let path = [Segment::Key("service"), Segment::Key("replicas")];
let mut ed = Editor::open(src.as_bytes(), fig_yaml::format()?)?;
ed.set_value(&path, 5)?;
ed.set_trailing_comment(&path, "bumped for Black Friday")?;
std::fs::write("config.yaml", ed.source()?)?;
// serde_json-style, in any format you depend on
let cfg: Config = fig_yaml::from_str(ed.source()?)?;
let toml = fig_toml::to_string(&cfg)?;[dependencies]
fig = "6"
fig-yaml = "6" # one crate per format
fig-toml = "6"fig is pure Rust: no C compiler or other toolchain. 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, and for C (or Zig, or anything else
that calls C), bindings/c/include/fig.h.
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.
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.
- 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
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.
adam@diaryx.org, or open an issue.