https://github.com/muhammad-fiaz/configforge-lua
An open-source CLI tool to convert configuration files between formats.
https://github.com/muhammad-fiaz/configforge-lua
config-forge configforce convert-files converter converter-app lua lua-application lua-programming lua-script
Last synced: 4 days ago
JSON representation
An open-source CLI tool to convert configuration files between formats.
- Host: GitHub
- URL: https://github.com/muhammad-fiaz/configforge-lua
- Owner: muhammad-fiaz
- License: mit
- Created: 2026-01-13T08:00:38.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-13T08:04:48.000Z (5 months ago)
- Last Synced: 2026-04-22T15:40:31.852Z (2 months ago)
- Topics: config-forge, configforce, convert-files, converter, converter-app, lua, lua-application, lua-programming, lua-script
- Language: Lua
- Homepage:
- Size: 15.6 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# ConfigForge
An open-source CLI tool to convert configuration files between formats.
## Supported Formats
- **JSON** (`.json`) - Strict standard JSON.
- **YAML** (`.yaml`, `.yml`) - Block and flow styles supported.
- **TOML** (`.toml`) - Standard sections and key-value pairs.
- **ENV** (`.env`) - Key-value environment variables with nesting support via delimiters.
## Prerequisites
- **Lua 5.4**: The tool requires Lua 5.4 runtime environment.
- Windows: [Lua Binaries](http://luabinaries.sourceforge.net/)
- Linux: `sudo apt install lua5.4`
- macOS: `brew install lua`
## Installation
1. **Clone the repository:**
```bash
git clone https://github.com/muhammad-fiaz/configforge-lua.git
cd configforge-lua
```
2. **Verify Installation:**
Run the help command (or run without arguments) to verify:
```bash
lua configforge.lua
```
## Usage and Examples
The tool officially supports **Any-to-Any** conversion. You can convert from any supported format to any other supported format.
### 1. Example Files
Create an `example.json` file with the following content:
```json
{
"app": {
"name": "ConfigForge",
"version": "1.0.0",
"debug": true,
"port": 8080
},
"database": {
"host": "localhost",
"retries": 3
},
"features": [
"conversion",
"validation",
"diff"
]
}
```
### 2. Format Conversion
**Common Conversions (JSON Source)**
```bash
lua configforge.lua convert example.json example.yaml
lua configforge.lua convert example.json example.toml
lua configforge.lua convert example.json example.env
```
**Any-to-Any Examples**
It is valid to convert between any pair of formats:
*YAML to TOML*
```bash
lua configforge.lua convert example.yaml output.toml
```
*ENV to JSON*
```bash
lua configforge.lua convert example.env output.json
```
*TOML to YAML*
```bash
lua configforge.lua convert example.toml output.yaml
```
**Note on ENV Files**:
When converting *to* ENV, nested structures are flattened (e.g., `app.port` become `APP_PORT`).
When converting *from* ENV, this flat structure is preserved as keys (e.g., `APP_PORT` remains `APP_PORT`).
### 3. Validation
Check if a file has valid syntax.
```bash
lua configforge.lua validate example.json
# Output: Valid json syntax.
```
### 4. Diff Mode
Compare two configuration files to see structural differences. This works across different formats.
**Compare JSON vs YAML:**
```bash
lua configforge.lua diff example.json example.yaml
```
*Output (if identical):*
(No output means files are structurally identical)
**Compare ENV vs TOML:**
```bash
lua configforge.lua diff example.env example.toml
```
## Command Reference
| Command | Syntax | Description |
|---------|--------|-------------|
| `convert` | `convert ` | Convert file format. Supports JSON, YAML, TOML, ENV. |
| `validate` | `validate ` | Validate file syntax. |
| `diff` | `diff ` | Compare two files structurally. |
## Exit Codes
| Code | Description |
|------|-------------|
| `0` | Success |
| `1` | Generic Failure / Runtime Error |
| `2` | Usage Error (Invalid arguments) |
| `3` | I/O Error (File not found, permission denied) |
| `4` | Parse Error (Invalid syntax in config file) |
## Project Structure
```
configforge-lua/
├── configforge.lua # Entry point
├── main.lua # Wrapper entry point
├── LICENSE # MIT License
├── README.md # Documentation
└── src/
├── cli.lua # CLI Logic
├── detect.lua # Format detection
├── diff.lua # Diff logic
├── errors.lua # Error handling
├── parser_*.lua # For JSON, YAML, TOML, ENV
└── writer_*.lua # For JSON, YAML, TOML, ENV
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.