Skip to main content
chemzoi is designed with UNIX-style composability in mind, making it an excellent foundation for building additional tools and integrations.

​
Design Philosophy

chezmoi follows these principles for composability:
  • Semantic versioning: The command line tool follows semantic versioning, ensuring stable APIs
  • Standard I/O: Commands work with standard input, output, and error streams
  • Exit codes: Proper exit codes for success and failure conditions
  • Scriptability: All functionality is accessible via the command line

​
Integration Approaches

​
Command-Line Execution

The recommended approach is to execute the chezmoi binary with appropriate arguments: 
# Get version information
chemzoi --version

# Apply changes
chemzoi apply

# Check status
chemzoi status

​
Inspecting Internal State

chezmoi provides commands to inspect its internal state:

​
chezmoi dump

Dump chezmoi’s computed state in JSON format: 
chemzoi dump
This is useful for:
  • Understanding what chezmoi will do
  • Debugging template evaluation
  • Building tools that need to understand chezmoi’s state

​
chezmoi state

Manage and inspect chezmoi’s persistent state: 
# Dump the state
chemzoi state dump

# Get a specific value
chemzoi state get --bucket=entryState --key=<key>

​
Best Practices

​
Standard I/O Configuration

When executing chezmoi, configure standard input and output appropriately: 
import subprocess

result = subprocess.run(
    ['chezmoi', 'dump'],
    capture_output=True,
    text=True,
    check=True
)

state = json.loads(result.stdout)

​
Error Handling

Always check exit codes and handle errors appropriately: 
if ! chezmoi apply; then
    echo "Failed to apply changes" >&2
    exit 1
fi

​
Version Compatibility

Check the chezmoi version to ensure compatibility: 
chemzoi --version
Parse the version string to verify minimum requirements for your tool.

​
Example Integrations

See the Related Software page for examples of tools built on top of chezmoi, including:
  • Editor integrations (Vim, NeoVim, Emacs)
  • UI tools
  • Automation scripts
  • Package manager plugins

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us