Release v0.2.2 (What’s new?).
Welcome to home_secret_toml Documentation¶
Modern software development presents an increasingly complex credential management challenge. As cloud services proliferate and microservice architectures become standard, developers face exponential growth in sensitive information requiring secure storage and convenient access—API keys, database credentials, authentication tokens, and service endpoints.
This complexity creates a fundamental tension: developers need immediate access to credentials during development while maintaining rigorous security standards. Traditional approaches, from hardcoded secrets to scattered environment variables, fail to address the sophisticated demands of contemporary multi-platform, multi-account development workflows.
The consequences of inadequate credential management extend beyond inconvenience. Security breaches, development inefficiencies, and maintenance nightmares plague teams using fragmented approaches. What developers need is a systematic solution that unifies security, accessibility, and scalability into a coherent framework.
HOME Secret TOML emerges as a response to these challenges—a comprehensive local credential management system built on structured TOML configuration and intelligent Python integration. Unlike nested JSON structures, TOML’s flat key-value format provides immediate context visibility in every line, making secrets easy to navigate and edit. This approach transforms credential management from a necessary evil into a streamlined development asset.
Key Features
Flat Key Structure: Every secret is a single line with full path context—no nested brackets to manage
Comment Support: Native
#comments for documentation directly in the secrets fileZero Dependencies: Uses only Python 3.11+ standard library (
tomllib)Dual Usage: Copy single file to your project OR
pip installas a packageCLI Tool:
hst lsto list secrets,hst gen-enumto generate IDE autocomplete codeIDE Support: Generated enum classes provide full autocomplete and type checking
Quick Links
Install¶
home_secret_toml is released on PyPI, so all you need is to:
$ pip install home-secret-toml
To upgrade to latest version:
$ pip install --upgrade home-secret-toml
Quick Start¶
Create
~/home_secret.tomlwith your secrets:
# GitHub credentials
github.accounts.personal.account_id = "myuser"
github.accounts.personal.users.dev.secrets.api_token.value = "ghp_xxxxxxxxxxxx"
# AWS credentials
aws.accounts.prod.secrets.deploy.creds = { access_key = "AKIA...", secret_key = "xxxx" }
Access secrets in Python:
from home_secret_toml import hs
# Direct value access
api_key = hs.v("github.accounts.personal.users.dev.secrets.api_token.value")
# Token-based (lazy) access
token = hs.t("github.accounts.personal.users.dev.secrets.api_token.value")
api_key = token.v # Resolved when accessed
Use CLI to explore and generate code:
# List all secrets (values are masked)
$ hst ls
github.accounts.personal.account_id = "***"
github.accounts.personal.users.dev.secrets.api_token.value = "gh***xx"
# Filter secrets
$ hst ls --query "github personal"
# Generate enum file for IDE autocomplete
$ hst gen-enum
Single-File Usage (No pip install)¶
For projects where you want zero dependencies, simply copy home_secret_toml.py to your project:
# Copy the file and import directly
from home_secret_toml import hs
api_key = hs.v("github.accounts.personal.users.dev.secrets.api_token.value")
Requirements: Python 3.11+ (for built-in tomllib module)
AI Agent Skill¶
Want your AI coding assistant to use this library? Simply copy the Agent Skill directory to your AI’s skill folder (e.g., .claude/skills/ for Claude Code). The AI will then be able to read credentials from ~/home_secret.toml automatically.