go-toml

go-toml (v1) is a Go library for working with TOML configuration files. It parses TOML text into a Tree structure that can be navigated with dot-separated key paths, converted to and from Go structs via Marshal/Unmarshal, or queried with a JSONPath-like expression language in its query subpackage.

The module ships three companion CLI tools — tomll (a TOML linter/formatter), tomljson (TOML to JSON), and jsontoml (JSON to TOML) — distributed both as Go binaries and as a Docker image, useful for scripting and CI pipelines that touch TOML files without writing Go code.

This is the legacy v1 line of the project. Development has moved to go-toml v2 (a separate module path, github.com/pelletier/go-toml/v2), which is faster, spec-compliant, and actively maintained; v1 remains widely imported by existing codebases but receives no further feature work.

What You Get

• Tree API for loading TOML from bytes, strings, readers, or files and navigating it with dot-separated key paths
• Struct marshaling and unmarshaling via toml tags, including comment, multiline, literal, and commented-field options
• A JSONPath-like query language (in the query subpackage) for pulling specific values out of a document without walking the tree manually
• Line/column position tracking on every parsed node, surfaced in syntax error messages
• Three standalone CLI tools — tomll, tomljson, jsontoml — plus a published Docker image for TOML linting and JSON conversion in scripts or CI

Common Use Cases

• Reading application configuration files into typed Go structs at startup
• Converting between TOML and JSON in build scripts or CI pipelines using the tomljson/jsontoml CLI tools
• Programmatically inspecting or rewriting TOML documents (e.g. config migration tools) via the Tree API
• Linting and auto-formatting TOML files with tomll as a pre-commit or CI check

Under The Hood

Architecture A hand-written lexer/parser pair (lexer.go, parser.go, token.go) feeds toml.go’s Load*/LoadBytes entrypoints, producing a *Tree backed by a map[string]interface{} whose values are wrapped tomlValue nodes, nested *Tree nodes, or []*Tree slices; marshal.go and tomltree_create.go/tomltree_write.go add reflection-based struct marshaling and tree serialization on top of that same model. The query subpackage layers its own independent lexer/parser/matcher (query/lexer.go, query/parser.go, query/match.go) over the identical Tree, so document traversal happens through two separate code paths — direct GetPath calls or compiled query expressions — that both ultimately walk the same values map, meaning any change to the Tree’s internal representation ripples through Marshal, Unmarshal, and Query alike.

Tech Stack go.mod pins module github.com/pelletier/go-toml at go 1.12 with an empty go.sum — there are no third-party runtime dependencies, and TOML parsing is entirely hand-rolled rather than delegated to a parser-generator or external grammar library. The one borrowed piece is localtime.go, vendored from Google’s civil library (Apache 2.0) for local date/time types. The cmd/ directory holds four thin CLI wrappers (tomll, tomljson, jsontoml, tomltestgen) built only on the standard library plus the root package. CI runs on Azure Pipelines with gofmt, coverage, and multi-version Go test jobs, and a Dockerfile publishes the CLI tools to Docker Hub.

Code Quality Thirteen _test.go files at the repo root (parser_test.go, marshal_test.go, lexer_test.go, keysparsing_test.go, position_test.go, token_test.go, tomltree_create_test.go, tomltree_write_test.go, localtime_test.go, toml_test.go, toml_testgen_test.go, and more) plus a dedicated test suite inside query/ give broad coverage across lexing, parsing, marshaling, and querying, including a run of the shared upstream TOML compliance suite via toml_testgen_test.go. Error handling relies on plain error returns (errors.New/fmt.Errorf) rather than a typed error hierarchy, and LoadBytes recovers from internal parser panics and converts them into normal returned errors. Type safety is limited by design — Tree.Get and query results return interface{}, pushing type assertions onto callers. CI enforces gofmt but there’s no additional linter configuration.

API Design The Tree API’s dot-path Get/GetPath/Set/Delete methods and the JSONPath-like query subpackage are the two ergonomic standouts, giving callers either generic document traversal or single-expression value extraction — a broader surface than most Go TOML libraries, which typically offer only Unmarshal-into-struct. Struct-tag support (toml, comment, commented, multiline, literal, default) is comprehensive for a v1-era library. The tradeoff is inherited complexity for consumers: interface{}-typed results force manual type assertions, and the project’s own documentation now actively redirects every new user to go-toml v2’s stricter, faster API — so v1’s design reads as a snapshot of pre-v2 idioms rather than a current reference point.