Registry / serialization / toml-cli

toml-cli

JSON →
library0.8.2pypypiunverified

toml-cli is a command-line interface tool designed for reading and writing keys and values within TOML configuration files. It is particularly useful for scripting and automating modifications to TOML files without requiring a full text editor. The library is currently at version 0.8.2 and appears to have an active release cadence.

pip install toml-cli
INSTALL
IMPORT
SIG · TOML-CLI
T
toml-cli
serializationpythonv0.8.2
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

This quickstart demonstrates how to use the `toml` command-line tool from Python scripts using `subprocess` to get and set values in a TOML file. It creates a temporary `test.toml` file, performs operations, and then cleans up.

import subprocess import os # Create a dummy TOML file for demonstration toml_content = """ [tool.poetry] name = "my-project" version = "0.1.0" authors = ["John Doe <john.doe@example.com>"] [database] host = "localhost" port = 5432 """ with open("test.toml", "w") as f: f.write(toml_content) print("Original TOML content:") print(toml_content) # Get a value print("\nGetting tool.poetry.name:") result = subprocess.run(["toml", "get", "--toml-path", "test.toml", "tool.poetry.name"], capture_output=True, text=True, check=True) print(f"Name: {result.stdout.strip()}") # Set a value print("\nSetting tool.poetry.version to 0.2.0:") subprocess.run(["toml", "set", "--toml-path", "test.toml", "tool.poetry.version", "0.2.0"], check=True) # Verify the set value result = subprocess.run(["toml", "get", "--toml-path", "test.toml", "tool.poetry.version"], capture_output=True, text=True, check=True) print(f"New Version: {result.stdout.strip()}") # Add a section and a value (set command can add if key doesn't exist) print("\nAdding/Setting database.user:") subprocess.run(["toml", "set", "--toml-path", "test.toml", "database.user", "admin"], check=True) # Read the entire updated file print("\nUpdated TOML content:") updated_content = subprocess.run(["cat", "test.toml"], capture_output=True, text=True, check=True) print(updated_content.stdout) # Clean up os.remove("test.toml")
toml --version
Debug
Known issues
breakingIn version 0.7.0, the `set` command was fixed to fail if the specified key was not found. Scripts that previously relied on `set` silently doing nothing or implicitly creating keys might experience failures.
fix
Ensure the target key or path exists before attempting to set its value, or handle the non-zero exit code in scripts.
affects: >=0.7.0
breakingVersion 0.7.0 included a fix for the `get` command when dealing with arrays of tables. This correction means that scripts which previously worked around or relied on the buggy behavior might now produce different or unexpected results.
fix
Review and update scripts that interact with arrays of tables using `toml get` to align with the corrected behavior.
affects: >=0.7.0
gotchatoml-cli is primarily a command-line interface tool and is not designed for direct programmatic import as a Python library (e.g., `import toml_cli`). Its functionality should be accessed by invoking the `toml` command via `subprocess` or directly in a shell environment.
fix
When using in Python, call the `toml` command via `subprocess.run()` or similar methods.
affects: all
gotchaStarting from version 0.7.0, the tool provides improved exit codes and more informative error messages. While beneficial, this might change the behavior of scripts that previously did not explicitly check exit codes or relied on specific (less verbose) error output.
fix
Update scripts to correctly interpret and handle the standardized exit codes and enhanced error messages provided by the `toml` command.
affects: >=0.7.0
Errors
Common errors & fixes
toml-cli: command not found
The `toml-cli` executable is not installed or its directory is not included in the system's PATH environment variable.
fix
pip install toml-cli
Error: config.toml does not exist.
The specified TOML file could not be found at the given path.
fix
Ensure the file path is correct and the TOML file exists, or create the file.
Error: The file path must be a TOML file.
The provided file name or path does not end with a `.toml` extension, which `toml-cli` requires for identification.
fix
Rename the file to have a `.toml` extension or provide a path to a file with a valid TOML extension.
Error: Could not parse TOML file: example.toml
The specified TOML file contains syntax errors or is not a valid TOML document.
fix
Correct the syntax errors within the TOML file to conform to the TOML specification.
Upgrade
Version history
0.8.2latest on PyPI · released Sep 12, 2025
Audit
Dependencies
pythonrequiredRequires Python 3.10 or higher.
Agent activity
10 hits · last 30 days
node
8
Amazon
1
OpenAI (training)
1
Resources
toml-cli — pip install toml-cli · libregistry