hocon2 — HOCON Conversion CLI for Go

HOCON conversion tools for Go — convert HOCON configuration files to JSON, YAML, TOML, and Java Properties.

HOCON (Human-Optimized Config Object Notation) is a superset of JSON designed for human readability. It supports comments, substitutions (${var}), includes, omitted quotes/commas, and more. hocon2 lets you convert HOCON files to widely-supported formats for use with tools that don't natively understand HOCON.

Powered by go.hocon parser. Conformance tested against Lightbend's reference test suite.

Implemented by Claude Code (Anthropic) — designed and built end-to-end with Claude Code. Reviewed by GitHub Copilot and OpenAI Codex.

Quick Start

1. Install

Go

go install github.com/o3co/hocon2/cmd/hocon2json@latest
go install github.com/o3co/hocon2/cmd/hocon2yaml@latest
go install github.com/o3co/hocon2/cmd/hocon2toml@latest
go install github.com/o3co/hocon2/cmd/hocon2properties@latest

Binary releases

Download pre-built binaries from the releases page (Linux/macOS/Windows, amd64/arm64).

2. Use

# Convert a file
hocon2json app.conf

# Read from stdin
cat app.conf | hocon2yaml

# Show help
hocon2json --help

Why hocon2?

HOCON is great for authoring config, but many tools only understand JSON, YAML, or TOML. hocon2 bridges this gap:

• Write config in HOCON (readable, composable, DRY)
• Deploy in whatever format your tools need (JSON for Kubernetes, YAML for Helm, TOML for Rust tools, Properties for Java)
• Validate syntax in CI before deployment (-validate flag)

Supported Formats

Command	Output Format
hocon2json	JSON
hocon2yaml	YAML
hocon2toml	TOML
hocon2properties	Java Properties

Usage

Options

# Compact JSON output (no whitespace)
hocon2json -compact app.conf

# Custom indentation width (default: 2)
hocon2json -indent 4 app.conf

# Write output to a file
hocon2json -o output.json app.conf

# Overwrite an existing output file
hocon2json -o output.json -overwrite app.conf

-compact and -indent are available for hocon2json only. -o and -overwrite work with all commands.

Multiple file merge

Multiple files can be passed as arguments. They are merged with right-precedence — the last file wins for conflicting keys:

hocon2toml base.conf env.conf local.conf

This is equivalent to local.conf overriding env.conf, which overrides base.conf. Useful for layered configuration (base → environment → local overrides).

Environment variables

HOCON substitutions (${VAR}) resolve against environment variables:

# Pass environment variables inline
DB_HOST=prod-db.example.com hocon2json app.conf

# Or export them
export DB_HOST=prod-db.example.com
hocon2json app.conf

Given app.conf:

database {
  host = ${DB_HOST}
  host = ${?DB_HOST}  # optional: use only if DB_HOST is set
}

Example

Given app.conf:

database {
  host = "localhost"
  port = 5432
  pool_size = 10
}

// Substitution
api_url = "https://"${database.host}":8080"

$ hocon2json app.conf
{
  "api_url": "https://localhost:8080",
  "database": {
    "host": "localhost",
    "pool_size": 10,
    "port": 5432
  }
}

Build

make all      # vet + test + build
make build    # build only
make test     # test only
make install  # install all binaries

Related Projects

Project	Language	Registry	Description
go.hocon	Go	pkg.go.dev	HOCON parser for Go (used by this project)
ts.hocon	TypeScript	npm	HOCON parser for TypeScript/Node.js
rs.hocon	Rust	crates.io	HOCON parser for Rust

All implementations are full Lightbend HOCON spec compliant.

Best Practices

CI/CD Integration

• Use hocon2json -validate to check HOCON syntax in CI pipelines before deployment
• Use -env-file to inject environment-specific variables without polluting the shell environment

Config Validation in CI

# Example: GitHub Actions
- name: Validate config
  run: hocon2json -validate config/prod.conf

Multi-File Merging

• Merge order matters: later files override earlier ones

• Use base.conf + env.conf pattern for environment-specific overrides:

  hocon2json base.conf prod.conf > config.json

License

Apache 2.0 — see LICENSE.