A visual configuration management tool for creating, editing, and validating application settings with intelligent rule-based automation.
Live Demo β’ Quick Start β’ Features β’ Documentation
Guido is a web-based GUI application that simplifies the management of complex configuration files. Instead of manually editing JSON, YAML, or other config formats, Guido provides:
- Visual editing of configuration fields with validation
- Intelligent rules that automatically enable/disable settings based on conditions
- Template system with reusable configuration schemas
- Multi-format support for JSON, YAML, CSV, .env, .properties, and .txt files
Visit quotentiroler.github.io/Guido to use Guido directly in your browser.
# Clone the repository
git clone https://github.com/quotentiroler/Guido.git
cd Guido
# Install dependencies
npm install
# Start development server
npm run devOpen http://localhost:5173 in your browser.
Edit configuration fields through an intuitive UI with:
- Field metadata (descriptions, examples, documentation links)
- Real-time validation (integers, booleans, URLs, regex patterns, enums)
- Checkbox-based field selection for export
Define conditional logic that automatically manages field dependencies:
If "Repository" is set to "MongoDb"
Then "MongoDbOptions.ConnectionString" must be set
Rule States:
| State | Description |
|---|---|
set |
Field must be enabled and have a value |
set_to_value |
Field must equal a specific value |
contains |
Field contains value as a discrete item: an array element, or (for a string) an exact match. Not a substring match |
gt / lt / gte / lte |
Numeric comparison of the field value against value (condition-only) |
The included MCP (Model Context Protocol) server enables AI assistants like Claude to manage Guido templates programmatically.
A .guido.json template consists of:
{
"name": "My App Settings",
"fileName": "appsettings.json",
"version": "1.0.0",
"description": "Configuration template for My App",
"owner": "MyOrganization",
"application": "My App",
"docs": "https://docs.example.com",
"command": "docker run myapp:latest",
"fields": [...],
"ruleSets": [...]
}Each field describes a configuration option:
{
"name": "Database.ConnectionString",
"value": "Server=localhost;Database=mydb",
"info": "Connection string for the primary database",
"example": "Server=localhost;Database=mydb;User=admin",
"range": "string",
"link": "https://docs.example.com/connection-strings",
"checked": true
}Field Properties:
| Property | Type | Description |
|---|---|---|
name |
string | Field identifier (use dots for nesting:Section.Subsection.Key) |
value |
string| number | boolean | string[] | Default value |
info |
string | Description shown in tooltip |
example |
string | Example value |
range |
string | Validation rule (see below) |
link |
string? | URL to documentation |
checked |
boolean? | Whether field is enabled for export |
secret |
boolean? | Never printed with a value in generated files or messages |
Range Types:
| Range | Description |
|---|---|
string |
Any string value (unbounded) |
boolean |
Must be true or false |
integer |
Must be a whole number |
integer(min..max) |
Integer within range (e.g., integer(1..65535)) |
string(min..max) |
String with length limits (e.g., string(0..255)) |
url |
Must be a valid URL |
string[] |
Array of strings |
integer[] |
Array of integers |
string[min..max] |
Array with size limits (e.g., string[1..10]) |
opt1||opt2||opt3 |
Must match one of the options |
(opt1||opt2)[] |
Array of options ((opt1||opt2)[min..max] limits its size) |
^regex$ |
Must match the regex pattern; a range anchored with ^ or $ is always a regex |
In flat settings files (.env, .properties, .ini, .txt, command-line args) an array-typed field is written as a comma list: SPRING_PROFILES_ACTIVE=production,metrics. An empty value (KEY=) counts as unset.
Rules define conditional relationships between fields:
{
"description": "MongoDB requires connection string",
"conditions": [
{ "name": "Repository", "state": "set_to_value", "value": "MongoDb" }
],
"targets": [
{ "name": "MongoDbOptions.ConnectionString", "state": "set" }
]
}Logic: If the conditions match, then ALL targets are enforced. Conditions combine per the rule's match: all (default, AND - every condition must hold) or any (OR - at least one).
A ruleset can also declare cardinality constraints over a set of fields (validated against a config, not applied as rules):
{
"constraints": [
{ "kind": "exactly-one", "fields": ["MongoDb", "SQLite", "Postgres"] }
]
}kind is exactly-one (exactly 1 of the fields set), at-least-one (>= 1), at-most-one (<= 1), or all-or-none (none or every field, e.g. a certificate and its key). A field counts as set when it is enabled with a non-empty value.
RuleDomain Properties:
| Property | Type | Description |
|---|---|---|
name |
string | Field name to evaluate/affect |
state |
set | set_to_value | contains | gt | lt | gte | lte |
Condition/target type |
value |
string? | Value for set_to_value, contains, or the numeric comparisons |
valueField |
string? | Compare against another field's value instead of value (e.g. MinPort lte field MaxPort). Condition-side; for set_to_value and the numeric comparisons |
not |
boolean? | Negate the condition/target |
Guido cannot describe configuration structures with dynamic arrays of complex objects where users need to add/remove items at runtime. The dot notation flattening (e.g., Plugins.0.Name, Plugins.1.Name) works for fixed-size arrays but not for unbounded collections.
| Pattern | Example | Supported |
|---|---|---|
| Nested objects | Database.Connection.Host |
β |
| Simple arrays | AllowedOrigins with range: "string[]" |
β |
| Fixed-size object arrays | Servers.0.Host, Servers.1.Host |
β |
| Dynamic object arrays | Unlimited plugin definitions | β |
npm run validate "path/to/template.guido.json"Checks for:
- Rule contradictions
- Circular dependencies
- Invalid rule structures
- Field validation issues
npm run schema-to-guido "schema.json" -o "output.guido.json" \
--name "My Template" \
--version "1.0.0" \
--owner "MyOrg" \
--application "My App" \
--docs "https://docs.example.com"npm run guido-to-schema "template.guido.json" -o "output.schema.json"guido-contract keeps a template, the code that reads its settings, the docs and env example generated from it, and every environment's settings in agreement. It reads guido.contract.json (--config to override; guido-contract schema prints its JSON Schema):
{
"template": "app.guido.json",
"scan": {
"files": [{ "include": ["src/**/*.ts"], "exclude": ["**/*.test.ts"], "patterns": ["process-env", "workers-env"] }],
"ignore": ["CI"],
"ignoreBindingsFrom": ["wrangler.toml"]
},
"generate": {
"docs": { "path": "docs/environment-variables.md" },
"envExample": { "path": ".env.example", "requiredRuleset": "Deployed" }
},
"targets": [
{ "name": "prod", "source": { "type": "compose", "path": "docker-compose.prod.yml", "service": "api" }, "ruleset": "Deployed", "strict": true },
{ "name": "edge", "source": { "type": "wrangler", "path": "wrangler.toml", "env": "production", "secrets": { "file": "secrets.json" } }, "tag": "edge" }
]
}guido-contract check # generated files current, code reads match the template's fields
guido-contract generate # rewrite <!-- guido:fields #anchor --> tables and the env example
guido-contract validate [--target prod]
guido-contract all- Scan patterns:
process-env,env-helper-call(intEnv('X')),workers-env(env.X,c.env.X, destructuring),import-meta-env,spring-placeholder,java-getenv, or{ "regex": "...", "flags": "m" }with one capture group. - Sources:
dotenv,file(json, yaml, ini, properties, ... viaformat),compose(${X:-d}givesd,${X}is supplied at deploy time;interpolateresolves references from another source),wrangler(toml/json/jsonc vars of the top level or oneenv),spring(dir, layeredprofiles),secrets(names only),values(literals) andmerge. Every source takessecrets(names supplied at deploy time, inline or from a file such aswrangler secret list --format json),select(keep and rename keys) andexcludePrefixes. - Keys supplied at deploy time count as present; their values are not range- or rule-checked. Paths resolve against
root(default: the config's directory). WithGITHUB_ACTIONSset, problems print as::error::annotations.
| Script | Description |
|---|---|
npm run dev |
Start development server |
npm run build |
Build for production |
npm run preview |
Preview production build |
npm run test |
Run tests |
npm run test:watch |
Run tests in watch mode |
npm run lint |
Run ESLint |
npm run deploy |
Deploy to GitHub Pages |
- Frontend: React 19, TypeScript, Tailwind CSS
- Build: Vite, npm workspaces (monorepo)
- Testing: Vitest
- Deployment: GitHub Pages
We welcome contributions! Please see our Contributing Guide for details.
Before contributing, please read our Code of Conduct.
# Fork and clone the repo
git clone https://github.com/YOUR_USERNAME/Guido.git
cd Guido
# Install dependencies
npm install
# Run tests
npm test
# Start development server
npm run devThis project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Copyright 2024-2025 Maximilian Nussbaumer
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
