Crate cliclack

source ·
Expand description

Beautiful, minimal, opinionated CLI prompts inspired by the @clack/prompts npm package.

“Effortlessly build beautiful command-line apps” (C) original @clack.

💎 Fancy minimal UI.
✅ Simple API.
🧱 Comes with input, password, confirm, select, multiselect, spinner, progress_bar, and multi_progress prompts.
🧱 Styled non-interactive messages with log submodule.
🎨 Theme support.

§Usage

API is similar to the original Clack API besides of a few exceptions.

§Setup

The intro and outro/outro_cancel functions will print a message to begin and end a prompt session respectively.

use cliclack::{intro, outro};

intro("create-my-app")?;
// Do stuff
outro("You're all set!")?;

§Cancellation

Esc cancels the prompt sequence with a nice message. Ctrl+C will be handled gracefully (same as Esc) if you set up a Ctrl+C handler, eg. with the ctrlc crate.

§Components

All prompts can be constructed either directly, e.g. with Input::new, or with the convenience function, e.g. input().

§Input

The input prompt accepts a single line of text trying to parse it into a target type.

use cliclack::input;

let number: String = input("What is the meaning of life?")
    .placeholder("Not sure")
    .validate(|input: &String| {
        if input.is_empty() {
            Err("Value is required!")
        } else {
            Ok(())
        }
    })
    .interact()?;

§Password

The password prompt is similar to the input prompt, but it doesn’t echo the actual characters.

use cliclack::password;

let password = password("Provide a password")
    .mask('▪')
    .interact()?;

§Confirm

The confirm prompt asks for a yes/no answer. It returns a boolean (true/false).

‘Y’ and ‘N’ keys are accepted as an immediate answer.

use cliclack::confirm;

let should_continue = confirm("Do you want to continue?").interact()?;

§Select

The select prompt asks to choose one of the options from the list.

use cliclack::select;

let selected = select("Pick a project type")
    .item("ts", "TypeScript", "")
    .item("js", "JavaScript", "")
    .item("coffee", "CoffeeScript", "oh no")
    .interact()?;

§Multi-Select

The multi-select prompt asks to choose one or more options from the list. The result is a vector of selected items.

use cliclack::multiselect;

let additional_tools = multiselect("Select additional tools.")
    .item("eslint", "ESLint", "recommended")
    .item("prettier", "Prettier", "")
    .item("gh-action", "GitHub Actions", "")
    .interact()?;

§Spinner

use cliclack::spinner;

let spinner = spinner();
spinner.start("Installing...");
// Do installation.
spinner.stop("Installation complete");

§Progress Bar

use cliclack::progress_bar;

let progress = progress_bar(100);
progress.start("Installation...");
for _ in 0..100 {
     progress.inc(1);
}
progress.stop("Installation complete");

§Multi-Progress Bar

use cliclack::{multi_progress, progress_bar, spinner};

let multi = multi_progress("Doing stuff...");
let pb1 = multi.add(progress_bar(100));
let pb2 = multi.add(progress_bar(100).with_download_template());
let spinner = multi.add(spinner());

pb1.start("Installation...");
pb2.start("Downloading...");
spinner.start("Waiting...");

pb1.stop("Installation complete");
pb2.stop("Download complete");
spinner.stop("Done");

multi.stop();

§Logging

Plain text output without any interaction.

use cliclack::log;

log::info("Hello, world!")?;
log::warning("Something is wrong")?;
log::error("Something is terribly wrong")?;

§Theme

Custom UI is supported via the Theme trait.

use cliclack::{set_theme, Theme, ThemeState};

struct MagentaTheme;

impl Theme for MagentaTheme {
    fn state_symbol_color(&self, _state: &ThemeState) -> console::Style {
       console::Style::new().magenta()
   }
}

set_theme(MagentaTheme);

See examples/theme.rs for a complete example.

cargo run --example theme

Modules§

  • log
    Non-interactive information messages of different styles.

Structs§

  • Confirm
    A prompt that asks for a yes or no confirmation.
  • Input
    A prompt that accepts a single line of text input.
  • MultiProgress
    Renders other progress bars and spinners under a common header in a single visual block.
  • MultiSelect
    A prompt that asks for one or more selections from a list of options.
  • Password
    A prompt that masks the input.
  • ProgressBar
    A progress bar renders progress indication. Supports spinner and download templates. Can be used as a single progress bar and as part of a multi-progress bar (see MultiProgress).
  • Select
    A prompt that asks for one selection from a list of options.

Enums§

Traits§

  • Theme
    Defines rendering of the visual elements. By default, it implements the original @Clack/prompts theme.
  • Validate
    Converts different types of external closures into internal validation functions.

Functions§