feat(cmd/csvpp): add CLI tool and documentation

.github/workflows/ci.yml

@@ -22,6 +22,9 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
+      - name: Install X11 dependencies
+        run: sudo apt-get update && sudo apt-get install -y libx11-dev
+
       - name: Setup Go
         uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5.6.0
         with:
@@ -39,6 +42,9 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
+      - name: Install X11 dependencies
+        run: sudo apt-get update && sudo apt-get install -y libx11-dev
+
       - name: Setup Go
         uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5.6.0
         with:

README.md

@@ -16,6 +16,8 @@ CSV++ extends traditional CSV to support **arrays** and **structured fields** wi
 - Struct mapping with `csvpp` tags (Marshal/Unmarshal)
 - Configurable delimiters
 - Security-conscious design (nesting depth limits)
+- **[csvpputil](./csvpputil/)** - JSON/YAML conversion utilities
+- **[csvpp CLI](./cmd/csvpp/)** - Command-line tool for viewing and converting CSV++ files
 
 ## Requirements
 
@@ -258,81 +260,30 @@ type Record struct {
 
 ## JSON/YAML Conversion (csvpputil)
 
-The `csvpputil` package provides utilities for converting CSV++ data to JSON and YAML formats.
+Utility package for converting CSV++ data to JSON and YAML formats with streaming support.
 
-### Installation
+For details, see [csvpputil/README.md](./csvpputil/README.md).
 
-```bash
-go get github.com/osamingo/go-csvpp/csvpputil
-```
-
-### Quick Conversion
-
-```go
-import "github.com/osamingo/go-csvpp/csvpputil"
-
-// Convert to JSON
-jsonData, err := csvpputil.MarshalJSON(headers, records)
+## CLI Tool (csvpp)
 
-// Convert to YAML
-yamlData, err := csvpputil.MarshalYAML(headers, records)
+A command-line tool for viewing, converting, and validating CSV++ files.
 
-// Write directly to io.Writer
-err = csvpputil.WriteJSON(w, headers, records)
-err = csvpputil.WriteYAML(w, headers, records)
-```
-
-### Streaming Output
-
-For large datasets, use streaming writers:
-
-```go
-// JSON streaming
-w := csvpputil.NewJSONArrayWriter(out, headers)
-for _, record := range records {
-    if err := w.Write(record); err != nil {
-        return err
-    }
-}
-if err := w.Close(); err != nil {
-    return err
-}
-
-// YAML streaming
-w := csvpputil.NewYAMLArrayWriter(out, headers)
-for _, record := range records {
-    if err := w.Write(record); err != nil {
-        return err
-    }
-}
-if err := w.Close(); err != nil {
-    return err
-}
-```
+```bash
+# Install
+go install github.com/osamingo/go-csvpp/cmd/csvpp@latest
 
-### Example Output
+# Validate
+csvpp validate input.csvpp
 
-Given CSV++ data:
-```
-name,tags[],geo(lat^lon)
-Alice,go~rust,35.6762^139.6503
-```
+# Convert to JSON/YAML
+csvpp convert -i input.csvpp -o output.json
+csvpp convert -i input.csvpp -o output.yaml
 
-JSON output:
-```json
-[{"name":"Alice","tags":["go","rust"],"geo":{"lat":"35.6762","lon":"139.6503"}}]
+# Interactive TUI view
+csvpp view input.csvpp
 ```
 
-YAML output:
-```yaml
-- name: Alice
-  tags:
-  - go
-  - rust
-  geo:
-    lat: "35.6762"
-    lon: "139.6503"
-```
+For more details, see [cmd/csvpp/README.md](./cmd/csvpp/README.md).
 
 ## Compatibility
 

cmd/csvpp/README.md

@@ -0,0 +1,106 @@
+# csvpp CLI
+
+A command-line tool for working with CSV++ files.
+
+## Installation
+
+```bash
+go install github.com/osamingo/go-csvpp/cmd/csvpp@latest
+```
+
+Or build from source:
+
+```bash
+go build -o csvpp ./cmd/csvpp
+```
+
+## Commands
+
+### validate
+
+Validate CSV++ file syntax.
+
+```bash
+# Validate a file
+csvpp validate input.csvpp
+
+# Validate from stdin
+cat input.csvpp | csvpp validate
+```
+
+### convert
+
+Convert between CSV++ and other formats (JSON, YAML).
+
+```bash
+# CSV++ to JSON
+csvpp convert -i input.csvpp -o output.json
+csvpp convert -i input.csvpp --to json
+
+# CSV++ to YAML
+csvpp convert -i input.csvpp -o output.yaml
+csvpp convert -i input.csvpp --to yaml
+
+# JSON to CSV++
+csvpp convert -i input.json -o output.csvpp
+csvpp convert -i input.json --from json --to csvpp
+
+# YAML to CSV++
+csvpp convert -i input.yaml -o output.csvpp
+csvpp convert -i input.yaml --from yaml --to csvpp
+
+# Using stdin/stdout
+cat input.csvpp | csvpp convert --to json
+cat input.json | csvpp convert --from json --to csvpp
+```
+
+**Flags:**
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--input` | `-i` | Input file path |
+| `--output` | `-o` | Output file path |
+| `--from` | | Input format (csvpp, json, yaml) - auto-detected from extension |
+| `--to` | | Output format (csvpp, json, yaml) - auto-detected from extension |
+
+### view
+
+View CSV++ file in an interactive TUI table.
+
+```bash
+# View a file
+csvpp view input.csvpp
+
+# View from stdin
+cat input.csvpp | csvpp view
+```
+
+**Key Bindings:**
+
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` | Navigate rows |
+| `Space` | Toggle row selection |
+| `y` / `c` | Copy header + selected rows to clipboard (CSV++ format) |
+| `Esc` | Clear selection |
+| `q` / `Ctrl+C` | Quit |
+
+**Note:** When stdin is not a TTY (e.g., in a pipe), a plain text table is displayed instead of the interactive TUI.
+
+## Examples
+
+```bash
+# Validate and convert if valid
+csvpp validate data.csvpp && csvpp convert -i data.csvpp -o data.json
+
+# Round-trip conversion
+csvpp convert -i data.csvpp -o data.json
+csvpp convert -i data.json -o data_restored.csvpp
+
+# Quick preview
+csvpp view data.csvpp
+```
+
+## License
+
+See the [LICENSE](../../LICENSE) file in the repository root.