TOML CLI

0.8.2 · active · verified Tue Apr 14

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.

Warnings

breaking In 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.
breaking Version 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.
gotcha toml-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.
gotcha Starting 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.

Install

pip install toml-cli Install via pip

Quickstart

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")

view raw JSON →