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](https://github.com/mikaelmello/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

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

# Or use just
just build::release
```

### Basic Usage

```bash
# 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

```bash
# 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

```bash
# 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

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

### Custom Validation

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

## Examples

### Script Integration

```bash
#!/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

```yaml
# 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

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

## Command Reference

```bash
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

```bash
--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`:

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

[validation]
strict = true
```

Or use config files:

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

## Backend-Specific Features

### Stdin Support

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

### Exit Codes

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

### Quiet Mode

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

## Use Cases

### 1. Deployment Scripts

Collect deployment parameters interactively:

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

### 2. Server Configuration

Generate server configs with validation:

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

### 3. CI/CD Integration

Non-interactive mode with defaults:

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

### 4. Data Migration

Collect and validate migration parameters:

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

## More examples

See [examples/04-backends/cli/](../../examples/04-backends/cli/) for:

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

## Related Documentation

- [Installation](../installation.md) - Setup guide
- [Configuration](../configuration.md) - Configuration options
- [Field Types](../field_types.md) - Available field types
- [Examples](../../examples/04-backends/cli/) - Working examples

## Troubleshooting

### "Terminal not supported"

CLI requires a TTY. For non-interactive environments:

```bash
typedialog form config.toml --yes  # Use defaults
```

### "Validation failed"

Check validation rules and input format:

```bash
typedialog form config.toml --log-level debug
```

### "Output format error"

Ensure format is valid:

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

---

**Ready to start?** See [examples/04-backends/cli/](../../examples/04-backends/cli/)