221 lines
4.9 KiB
Markdown
221 lines
4.9 KiB
Markdown
# ConfigConvert CLI
|
|
|
|
A powerful CLI tool for bidirectional conversion between JSON, YAML, TOML, and ENV config formats with smart type inference, validation, flatten/unflatten operations, schema generation, and automatic shell completion support.
|
|
|
|
## Features
|
|
|
|
- **Bidirectional Conversion**: Convert between any combination of supported formats
|
|
- **Smart Type Inference**: Automatically detect and convert string values to appropriate Python types
|
|
- **Syntax Validation**: Validate syntax of input files before conversion
|
|
- **Flatten/Unflatten**: Transform nested structures to/from dot-notation keys
|
|
- **Schema Generation**: Generate JSON Schema from parsed configurations
|
|
- **Shell Completion**: Built-in support for bash, zsh, and fish completions
|
|
- **Offline Operation**: Runs entirely offline with minimal dependencies
|
|
- **Rich Output**: Beautiful terminal output using Rich library
|
|
|
|
## Installation
|
|
|
|
### From PyPI
|
|
|
|
```bash
|
|
pip install config-convert-cli
|
|
```
|
|
|
|
### From Source
|
|
|
|
```bash
|
|
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/config-convert-cli.git
|
|
cd config-convert-cli
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### Convert between formats
|
|
|
|
```bash
|
|
# Convert JSON to YAML
|
|
config-convert convert input.json --to yaml -o output.yaml
|
|
|
|
# Convert YAML to JSON with custom indentation
|
|
config-convert convert config.yaml --from yaml --to json --indent 4
|
|
|
|
# Convert ENV to JSON
|
|
config-convert convert .env --from env --to json
|
|
|
|
# Read from stdin
|
|
cat config.json | config-convert convert --stdin --from json --to yaml
|
|
|
|
# Pretty print output
|
|
config-convert convert config.json --to yaml --indent 2
|
|
```
|
|
|
|
### Validate syntax
|
|
|
|
```bash
|
|
# Validate a config file
|
|
config-convert validate config.yaml
|
|
|
|
# Validate from stdin
|
|
echo '{"name": "test"}' | config-convert validate --stdin --format json
|
|
```
|
|
|
|
### Flatten nested structures
|
|
|
|
```bash
|
|
# Flatten nested JSON to ENV format
|
|
config-convert flatten config.json --output flat.env
|
|
|
|
# Flatten to another structured format
|
|
config-convert flatten config.json --format yaml
|
|
```
|
|
|
|
### Unflatten to nested structures
|
|
|
|
```bash
|
|
# Unflatten ENV to JSON
|
|
config-convert unflatten flat.env --format json --output nested.json
|
|
```
|
|
|
|
### Generate JSON Schema
|
|
|
|
```bash
|
|
# Generate schema from config
|
|
config-convert schema config.json -o schema.json
|
|
|
|
# Generate and display schema
|
|
config-convert schema config.json
|
|
```
|
|
|
|
### List supported formats
|
|
|
|
```bash
|
|
config-convert formats
|
|
```
|
|
|
|
## Supported Formats
|
|
|
|
| Format | Extensions | Read | Write |
|
|
|--------|------------|------|-------|
|
|
| JSON | .json | Yes | Yes |
|
|
| YAML | .yaml, .yml| Yes | Yes |
|
|
| TOML | .toml | Yes | Yes |
|
|
| ENV | .env | Yes | Yes |
|
|
|
|
## Shell Completion
|
|
|
|
### Bash
|
|
|
|
```bash
|
|
# Install completions for current user
|
|
config-convert --install-completion bash
|
|
|
|
# Or source directly
|
|
source <(config-convert --show-completion bash)
|
|
```
|
|
|
|
### Zsh
|
|
|
|
```bash
|
|
config-convert --install-completion zsh
|
|
```
|
|
|
|
### Fish
|
|
|
|
```bash
|
|
config-convert --install-completion fish
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| CONFIG_CONVERT_THEME | Color theme for Rich output | default |
|
|
| CONFIG_CONVERT_INDENT | Default indentation for output | 2 |
|
|
|
|
## Exit Codes
|
|
|
|
| Code | Description |
|
|
|------|-------------|
|
|
| 0 | Success |
|
|
| 1 | General error |
|
|
| 2 | Invalid arguments |
|
|
| 3 | File not found |
|
|
| 4 | Syntax error in input |
|
|
| 5 | Conversion error |
|
|
|
|
## Development
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
# Create virtual environment
|
|
python -m venv venv
|
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
|
|
# Install dependencies
|
|
pip install -e ".[dev]"
|
|
|
|
# Run tests
|
|
pytest tests/ -v
|
|
|
|
# Run with coverage
|
|
pytest --cov=config_convert --cov-report=term-missing
|
|
|
|
# Run linting
|
|
ruff check .
|
|
```
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
config-convert-cli/
|
|
├── config_convert/
|
|
│ ├── __init__.py
|
|
│ ├── cli.py
|
|
│ ├── converters/
|
|
│ │ ├── __init__.py
|
|
│ │ ├── base.py
|
|
│ │ ├── json_converter.py
|
|
│ │ ├── yaml_converter.py
|
|
│ │ ├── toml_converter.py
|
|
│ │ └── env_converter.py
|
|
│ ├── utils/
|
|
│ │ ├── __init__.py
|
|
│ │ ├── type_inference.py
|
|
│ │ ├── flatten.py
|
|
│ │ └── schema.py
|
|
│ └── validators/
|
|
│ ├── __init__.py
|
|
│ └── syntax.py
|
|
├── tests/
|
|
│ ├── __init__.py
|
|
│ ├── conftest.py
|
|
│ ├── test_cli.py
|
|
│ ├── test_converters/
|
|
│ ├── test_type_inference.py
|
|
│ ├── test_flatten.py
|
|
│ ├── test_schema.py
|
|
│ ├── test_validators.py
|
|
│ └── fixtures/
|
|
├── scripts/
|
|
│ └── completions.py
|
|
├── pyproject.toml
|
|
├── requirements.txt
|
|
└── README.md
|
|
```
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Run tests and linting
|
|
5. Submit a pull request
|
|
|
|
## License
|
|
|
|
MIT License - see LICENSE file for details.
|