sparcli 0.2.0

Lightweight, cross-platform toolkit for styled CLI output and interactive input widgets
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

# sparcli

[![Crates.io](https://img.shields.io/crates/v/sparcli.svg)](https://crates.io/crates/sparcli)
[![Docs.rs](https://docs.rs/sparcli/badge.svg)](https://docs.rs/sparcli)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![MSRV](https://img.shields.io/badge/MSRV-1.88-blue.svg)](https://www.rust-lang.org)

A lightweight, cross-platform toolkit for **styled CLI output** and
**interactive input widgets** in Rust. It renders directly to the terminal via
[`crossterm`](https://crates.io/crates/crossterm) (no `ratatui` dependency) but
mirrors ratatui's familiar vocabulary (`Style`, `Color`, `Span`, `Line`,
`Text`), so the API feels at home if you already use ratatui.

sparcli is meant for small, lightweight CLI tools: a single accent color, muted
defaults, rounded borders, graceful `NO_COLOR` and non-terminal behavior. Heavy,
full-screen/retained TUIs are out of scope (that is what ratatui is for).

![sparcli output widgets](https://raw.githubusercontent.com/cgroening/rs-sparcli/main/images/screenshot-1.png)

![sparcli input widgets](https://raw.githubusercontent.com/cgroening/rs-sparcli/main/images/screenshot-2.png)

## Highlights

- **Output**: styled text, markup, tables (colspan, striping, wrap, titles),
  panels, alerts, rules, lists, trees, key-value lists, badges, progress bars,
  spinners, multi-progress, diffs, columns, live display, pager, and
  composition helpers (`align`, `pad`, `vstack`).
- **Input**: confirm, text (validation, char filters, history, ghost
  autocomplete), password, number (with a calculator), textarea, single/multi
  select, an inline fuzzy select, and a calendar date picker.
- **Unified theme** for input *and* output, set once and overridable per call.
- **Robust**: no panics on input, RAII terminal restore, `Result`-based errors.

## Install

```toml
[dependencies]
sparcli = "0.2"
# Opt-in features (the base stays small):
# sparcli = { version = "0.2", features = ["markup", "fuzzy", "pager"] }
```

MSRV: Rust 1.88 (edition 2024).

| Feature  | Adds                                              |
| -------- | ------------------------------------------------- |
| `markup` | `[bold red]…[/]` inline markup parsing            |
| `fuzzy`  | inline fuzzy-select (pulls in `nucleo-matcher`)   |
| `pager`  | paging via `$PAGER` / `less` / `more`             |
| `full`   | enables `markup`, `fuzzy` and `pager`             |

### From a local checkout or Git

To use an unpublished or local copy instead of the crates.io release, point
Cargo at the source directory or repository:

```toml
[dependencies]
# Local path (absolute or relative to your Cargo.toml):
sparcli = { path = "../sparcli" }
# Straight from Git:
# sparcli = { git = "https://github.com/cgroening/rs-sparcli", branch = "main" }
```

## Output example

```rust
use sparcli::prelude::*;
use sparcli::{Alert, Table};

fn main() -> sparcli::Result<()> {
    Alert::success("Build finished.").print()?;

    Table::new()
        .columns(["Name", "Status"])
        .row(["web-1", "online"])
        .row(["db-1", "online"])
        .striped(true)
        .print()?;
    Ok(())
}
```

Every output widget implements `Renderable`: call `.print()` to write to stdout,
or `.print_to(&mut writer)` to capture output. When stdout is not a terminal (a
pipe, a file, or with `NO_COLOR`), no escape codes are emitted.

## Input example

```rust
use sparcli::validate::non_empty;
use sparcli::{Confirm, Outcome, TextInput};

fn main() -> sparcli::Result<()> {
    if let Outcome::Submitted(name) =
        TextInput::new("Your name?").validate(non_empty()).run()?
    {
        if let Outcome::Submitted(true) = Confirm::new("Continue?").run()? {
            println!("Hello, {name}!");
        }
    }
    Ok(())
}
```

Prompts return `Outcome<T>` (`Submitted(value)`, `Cancelled`, or a fired
`Shortcut(id)`) and never panic. They require an interactive terminal; without
one they return `SparcliError::NoTerminal`.

## Theming

```rust
use sparcli::{Color, Theme, set_theme};

let theme = Theme {
    accent: Color::Rgb(180, 142, 173),
    unicode: true, // set false for ASCII-only glyphs
    ..Theme::default()
};
set_theme(theme);
```

The same theme drives both output widgets and input prompts.

## Examples

```sh
cargo run --example output_gallery --features markup,fuzzy,pager
cargo run --example output_dynamic --features pager  # spinner/progress/live
cargo run --example prompts --features fuzzy          # interactive; needs a TTY
cargo run --example output-readme --features markup   # screenshot collage
cargo run --example prompt-readme                     # non-interactive prompts
```

## Documentation

- [docs.rs/sparcli](https://docs.rs/sparcli) – the complete API reference (rustdoc, built with all features).
- [`DEVELOPMENT.md`](https://github.com/cgroening/rs-sparcli/blob/main/docs/DEVELOPMENT.md) – building, testing and contributing.
- [`CHANGELOG.md`](https://github.com/cgroening/rs-sparcli/blob/main/CHANGELOG.md) – release notes.
- `cargo doc --all-features --open` – build the same reference locally.

## License

MIT – see [`LICENSE`](LICENSE).