TypeDialog/docs/configuration.md

Configuration Files

Pre-configured settings for each TypeDialog backend and environment.

Overview

Configuration files are organized by backend (CLI, TUI, Web) and environment (default, dev, production).

config/
├── cli/
│   ├── default.toml       # Standard CLI settings
│   ├── dev.toml           # Development (debugging enabled)
│   └── production.toml    # Production (optimized, hardened)
├── tui/
│   ├── default.toml       # Standard TUI settings
│   ├── dev.toml           # Development features enabled
│   └── production.toml    # Optimized for deployment
└── web/
    ├── default.toml       # Standard web server settings
    ├── dev.toml           # Development (hot reload)
    └── production.toml    # Hardened for production

Backend Configurations

CLI Backend

command-line interface - Simple text-based forms for scripts and automation.

Config	Purpose	Debug	Colors	Timeout
default	Standard	No	Yes	300 s
dev	Development	Yes	Yes	300 s
production	Production	No	Yes	3600 s

Usage:

typedialog --config config/cli/production.toml form.toml

Features:

• Inline validation
• Optional mouse support
• Placeholder text display
• Help text display

TUI Backend

terminal user interface - Interactive multi-panel forms with navigation.

Config	Purpose	Borders	Animations	Render
default	Standard	Rounded	Enabled	Auto
dev	Development	Double	Enabled	Debug
production	Production	Rounded	Disabled	Optimized

Usage:

typedialog-tui --config config/tui/production.toml form.toml

Features:

• 3-panel layout (fields, input, buttons)
• Mouse support
• Keyboard navigation
• Real-time field updates

Web Backend

HTTP server - Browser-based forms with REST API.

Config	Purpose	CORS	HTTPS	Rate Limit
default	Standard	Localhost	No	Unlimited
dev	Development	Enabled	No	Unlimited
production	Production	Restricted	Required	100/min

Basic Usage:

typedialog-web form.toml
# Server starts on http://localhost:8080

With Options:

# Load defaults from .ncl file
typedialog-web form.toml --defaults values.ncl

# Save results to file after form submission
typedialog-web form.toml --output result.json

# Combine with custom locale
typedialog-web form.toml --defaults config.ncl --output result.json --locale es-ES

# Run on custom port
typedialog-web form.toml --port 9000

Features:

• HTML/CSS rendering
• CSRF protection
• Response caching
• Gzip compression
• Array field management (RepeatingGroup)
• Default value loading from Nickel (.ncl) or JSON
• Output to file (JSON format)

Configuration by Environment

Development Configuration

Enabled features for development and debugging:

# CLI Dev
debug_output = true
log_level = "debug"
show_field_types = true

# TUI Dev
show_field_indices = true
trace_rendering = false

# Web Dev
hot_reload = true
debug = true
logs = "/tmp/typedialog-web.log"

Usage:

typedialog --config config/cli/dev.toml form.toml
typedialog-tui --config config/tui/dev.toml form.toml
typedialog-web --config config/web/dev.toml

Production Configuration

Hardened settings optimized for deployment:

# CLI Production
debug_output = false
log_level = "error"
show_placeholders = false
timeout = 3600

# TUI Production
enable_animations = false
render_throttle = 16ms
max_fps = 60

# Web Production
require_https = true
csrf_enabled = true
rate_limit = 100
cache_ttl = 3600

Usage:

typedialog --config config/cli/production.toml form.toml
typedialog-tui --config config/tui/production.toml form.toml
typedialog-web --config config/web/production.toml

Common Settings

Form Configuration

[form]
title = "Form Title"
description = "Optional description"

[form.validation]
validate_on_change = true
show_errors_inline = true
strict_validation = true

Output Configuration

[output]
format = "json"          # json, yaml, toml, text
pretty_print = true
debug_output = false

Logging

[logging]
level = "info"           # debug, info, warn, error
file = "/var/log/typedialog/app.log"

Custom Configuration

Creating Custom Configurations

Create a new TOML file based on an environment template:

# Copy production config as base
cp config/cli/production.toml config/cli/custom.toml

# Edit for your needs
nano config/cli/custom.toml

# Use it
typedialog --config config/cli/custom.toml form.toml

Override Specific Settings

Use environment variables to override config:

# CLI Backend
export TYPEDIALOG_DEBUG=1
export TYPEDIALOG_LOG_LEVEL=debug
typedialog --config config/cli/default.toml form.toml

# TUI Backend
export TYPEDIALOG_TUI_BORDER=double
typedialog-tui --config config/tui/default.toml form.toml

# Web Backend
export TYPEDIALOG_WEB_PORT=3000
export TYPEDIALOG_WEB_CORS_ORIGINS="localhost,example.com"
typedialog-web --config config/web/default.toml

# Fragment Search Paths (All Backends)
export TYPEDIALOG_FRAGMENT_PATH="/path/to/fragments:/another/path/fragments"
# On Windows use semicolon separator:
# set TYPEDIALOG_FRAGMENT_PATH=C:\fragments;D:\other\fragments
typedialog form.toml

TYPEDIALOG_FRAGMENT_PATH:

Colon-separated list (semicolon on Windows) of directories to search for fragment files. Fragments are reusable form components loaded via includes directive in group definitions.

Search order:

1. Form's directory (backward compatible)
2. Directories in TYPEDIALOG_FRAGMENT_PATH (left to right)

Example:

export TYPEDIALOG_FRAGMENT_PATH="/usr/local/share/typedialog/fragments:$HOME/.typedialog/fragments"
typedialog form.toml

For complete documentation on fragment search paths, see: Fragment Search Paths - Cascading search, use cases, troubleshooting

CLI Backend Configuration Details

[terminal]
use_raw_mode = true          # Enable raw terminal mode
enable_mouse = false         # Mouse support
use_color = true             # Colored output

[appearance]
theme = "default"            # Color theme
show_help = true             # Display field help
show_placeholders = true     # Show placeholder text

[validation]
validate_on_change = true    # Real-time validation
show_errors_inline = true    # Inline error messages

[timeout]
max_duration = 3600          # Max form time (seconds)
input_timeout = 300          # Field input timeout

TUI Backend Configuration Details

[terminal]
use_raw_mode = true
enable_mouse = true
enable_scrolling = true
height = -1                  # -1 = auto
width = -1                   # -1 = auto

[ui]
show_borders = true
show_focus = true
highlight_on_hover = true
enable_animations = true

[appearance]
theme = "default"
border_style = "rounded"     # rounded, double, simple
color_scheme = "default"

[keyboard]
vi_mode = false
emacs_mode = false

[performance]
render_throttle = 16         # milliseconds
max_fps = 60                 # frames per second

Web Backend Configuration Details

[server]
host = "0.0.0.0"
port = 8080
workers = 4

[html]
css_framework = "none"       # bootstrap, tailwind, none
inline_styles = false
responsive = true
dark_mode = true

[submission]
method = "post"
webhook_url = "https://api.example.com/forms"
redirect_on_success = true
redirect_url = "https://example.com/thank-you"

[security]
csrf_enabled = true
rate_limit = 100             # requests per minute
require_https = true
add_security_headers = true

[performance]
cache_static = true
cache_ttl = 3600
enable_compression = true
compression_threshold = 1024

Distribution Configurations

When creating release distributions, all configurations are included:

# Build and package
just distro::build-release
just distro::create-package

# Result includes all configs
distribution/typedialog-0.1.0/
├── config/
│   ├── cli/
│   ├── tui/
│   └── web/
└── ...

Users can then choose configs during installation:

# Extract distribution
tar -xzf typedialog-0.1.0.tar.gz
cd typedialog-0.1.0

# Install
bash installers/install.sh

# Use specific config
typedialog --config ~/.config/typedialog/cli/production.toml form.toml

Best Practices

Development

• Use dev configurations for local development
• Enable debugging and verbose logging
• Use shorter timeouts for faster iteration

Testing

• Use default configurations for testing
• Run integration tests with all environments

Production

• Always use production configurations
• Verify HTTPS is enabled (web backend)
• Set appropriate rate limits
• Configure logging to persistent location
• Test thoroughly in staging first

Related Documentation

• BUILD_AND_DISTRIBUTION.md - Build guide
• DISTRIBUTION_WORKFLOW.md - Release workflow
• README.md - Main documentation