TypeDialog/docs/cli/README.md

TypeDialog CLI Backend

Command-line interface for TypeDialog prompts and forms.

Overview

The CLI backend (typedialog) provides interactive terminal prompts powered by the inquire library. Ideal for scripts, automation, CI/CD pipelines, and server-side tools.

Features

• 8 Prompt Types: text, confirm, select, multi-select, password, custom, editor, date
• JSON/YAML/TOML Output: Structured data for piping
• Validation: Built-in and custom validators
• Autocompletion: Smart suggestions for select prompts
• Non-interactive Mode: For automation (--yes flag)
• Stdin Support: Pipe data between commands

Quick Start

Installation

# From source
cargo build --release
sudo cp target/release/typedialog /usr/local/bin/

# Or use just
just build::release

Basic Usage

# Simple text prompt
typedialog text "Enter your name"

# Select from options
typedialog select "Choose environment" dev staging production

# Password prompt (masked input)
typedialog password "Enter password"

# Multi-select (space to select, enter to confirm)
typedialog multi-select "Choose features" auth logging metrics

With Forms

# Run a TOML form
typedialog form examples/01-basic/simple_form.toml

# Output as JSON
typedialog form config.toml --format json

# Non-interactive (use defaults)
typedialog form config.toml --yes

Output Formats

# JSON
typedialog form config.toml --format json > output.json

# YAML
typedialog form config.toml --format yaml > output.yaml

# TOML
typedialog form config.toml --format toml > output.toml

# Nickel
typedialog form config.toml --format nickel > output.ncl

Validation

Built-in Validators

[[fields]]
name = "email"
field_type = "Text"
validation = "email"  # email, url, number, etc.

Custom Validation

[[fields]]
name = "age"
field_type = "Text"
validation = "range(18..120)"
error_message = "Age must be between 18 and 120"

Examples

Script Integration

#!/bin/bash

# Collect user input
CONFIG=$(typedialog form deploy.toml --format json)

# Use in script
ENVIRONMENT=$(echo "$CONFIG" | jq -r '.environment')
REGION=$(echo "$CONFIG" | jq -r '.region')

echo "Deploying to $ENVIRONMENT in $REGION..."

CI/CD Pipeline

# GitHub Actions
- name: Collect deployment config
  run: |
    typedialog form .github/deploy-config.toml --yes --format json > config.json

- name: Deploy
  run: |
    ./deploy.sh --config config.json

Piping Between Commands

# Generate config → validate → deploy
typedialog form config.toml --format json | \
  jq '.environment = "production"' | \
  ./deploy.sh --stdin

Command Reference

typedialog --help               # Show help
typedialog text <prompt>        # Text input
typedialog confirm <prompt>     # Yes/no confirmation
typedialog select <prompt> <options>  # Single selection
typedialog multi-select <prompt> <options>  # Multiple selection
typedialog password <prompt>    # Password input
typedialog editor <prompt>      # Open editor
typedialog date <prompt>        # Date picker
typedialog form <file>          # Run form from TOML

Global Flags

--format <json|yaml|toml|nickel>  # Output format
--yes                              # Non-interactive mode
--config <file>                    # Config file
--log-level <level>                # Logging verbosity

Configuration

Global configuration in ~/.config/typedialog/config.toml:

[cli]
default_format = "json"
theme = "default"
log_level = "info"

[validation]
strict = true

Or use config files:

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

Backend-Specific Features

Stdin Support

# Pipe JSON to pre-fill form
cat data.json | typedialog form config.toml --stdin

Exit Codes

typedialog form config.toml
echo $?  # 0 = success, 1 = validation error, 2 = user cancelled

Quiet Mode

# Suppress all output except result
typedialog form config.toml --quiet --format json

Use Cases

1. Deployment Scripts

Collect deployment parameters interactively:

typedialog form deploy.toml --format json > deploy-config.json
./deploy.sh --config deploy-config.json

2. Server Configuration

Generate server configs with validation:

typedialog form server-config.toml --format toml > /etc/myapp/config.toml

3. CI/CD Integration

Non-interactive mode with defaults:

typedialog form .ci/config.toml --yes --format json

4. Data Migration

Collect and validate migration parameters:

typedialog form migration.toml --format yaml | ./migrate.py --config -

More examples

See examples/04-backends/cli/ for:

• Basic prompts
• Form automation
• Piping and scripting
• Validation examples
• CI/CD integration

Related Documentation

• Installation - Setup guide
• Configuration - Configuration options
• Field Types - Available field types
• Examples - Working examples

Troubleshooting

"Terminal not supported"

CLI requires a TTY. For non-interactive environments:

typedialog form config.toml --yes  # Use defaults

"Validation failed"

Check validation rules and input format:

typedialog form config.toml --log-level debug

"Output format error"

Ensure format is valid:

typedialog form config.toml --format json  # json, yaml, toml, or nickel

---

Ready to start? See examples/04-backends/cli/