Toml¶

PowerShell module for reading and writing TOML data, with full TOML 1.0.0 specification support.

Prerequisites¶

PowerShell 7.6 LTS
The PSModule framework for building, testing and publishing the module.

Installation¶

To install the module from the PowerShell Gallery, you can use the following command:

Install-PSResource -Name Toml
Import-Module -Name Toml

Usage¶

Parse a TOML string¶

$doc = ConvertFrom-Toml -InputObject @'
[database]
host = "localhost"
port = 5432
enabled = true
'@

$doc.Data.database.host     # "localhost"
$doc.Data.database.port     # 5432 [long]
$doc.Data.database.enabled  # $true

Import from a TOML file¶

$doc = Import-Toml -Path './config.toml'
$doc.FilePath   # absolute path to the file
$doc.Data       # OrderedDictionary of all top-level keys

Serialize an object to TOML¶

$toml = ConvertTo-Toml -InputObject ([ordered]@{
    title   = 'My App'
    version = 1
    server  = [ordered]@{
        host = 'localhost'
        port = 8080
    }
})
# title = "My App"
# version = 1
#
# [server]
# host = "localhost"
# port = 8080

Export to a TOML file¶

$config = [ordered]@{
    name    = 'example'
    enabled = $true
}
Export-Toml -InputObject $config -Path './output.toml'

Round-trip: file → modify → file¶

$doc = Import-Toml -Path './config.toml'
$doc.Data['version'] = 2
Export-Toml -InputObject $doc -Path './config.toml'

Normalize TOML text¶

Get-Content 'Cargo.toml' -Raw | Format-Toml
Format-Toml -Path 'Cargo.toml' -Indent 4

Format-Toml parses then re-serializes TOML text, producing consistent key quoting and canonical scalar forms — equivalent to ConvertFrom-Toml | ConvertTo-Toml as a single call. TOML itself has no indentation semantics; -Indent (default 2) only controls how many spaces are used to visually nest table headers and their keys by depth. Set -Indent 0 for the flat, unindented form.

Merge two TOML documents¶

$defaults = @'
[server]
host = "localhost"
port = 8080
'@

$overrides = @'
[server]
port = 9090
'@

Merge-Toml -BaseObject $defaults -OverrideObject $overrides
# [server]
# host = "localhost"
# port = 9090

Merge-Toml also accepts -Path/-LiteralPath for merging files, and a -Strategy of LastWins (default), FirstWins, or ErrorOnConflict for resolving scalar key conflicts. Nested tables are always deep-merged and arrays of tables are always concatenated.

TOML type mapping¶

TOML type	PowerShell type
String	`[string]`
Integer	`[long]`
Float	`[double]`
Boolean	`[bool]`
Offset date-time	`[System.DateTimeOffset]`
Local date-time	`[System.DateTime]`
Local date	`[System.DateTime]`
Local time	`[System.TimeSpan]`
Array	`[object[]]`
Table / Inline table	`[ordered]` hashtable
Array of tables	`[object[]]` of hashtables

Commands¶

Command	Description
`ConvertFrom-Toml`	Parse TOML text → `TomlDocument`
`ConvertTo-Toml`	Serialize object → TOML text
`Import-Toml`	Read TOML file → `TomlDocument`
`Export-Toml`	Write object or `TomlDocument` to file
`Format-Toml`	Normalize TOML text to canonical form
`Test-Toml`	Validate TOML text without throwing
`Merge-Toml`	Merge two TOML documents into one

Implementation notes¶

Pure PowerShell parser and serializer — no external TOML runtime dependency.
Duplicate keys and table redefinition are rejected per the TOML 1.0.0 spec.
Files are written as UTF-8 without BOM.

More examples¶

See the examples folder for runnable scripts. Use PowerShell help for per-command examples:

Get-Help ConvertFrom-Toml -Examples
Get-Help Import-Toml -Examples

Documentation¶

Full documentation is available at psmodule.io/Toml.

Contributing¶

Coder or not, you can contribute to the project! We welcome all contributions.

For Users¶

If you experience unexpected behavior, errors, or missing functionality, please open an issue on the issues tab.

For Developers¶

Please read the Contribution guidelines and pick up an existing issue or submit a new one.