Function paint 

pub fn paint(style: Style, s: &str) -> String

Apply an anstyle::Style to s and return an owned String.

Respects NO_COLOR and pipe detection via anstream.

Example

use cli_ui::styles::{paint, OK, CHECK};
let line = format!("{}  done", paint(OK, CHECK));

Examples found in repository

examples/subcommands.rs (line 140)

fn download(g: &Global, opt: DownloadOpt) {
    header!(
        "mytool",
        env!("CARGO_PKG_VERSION"),
        "batch file processor",
        "fast and parallel"
    );
    phase!("download", "{}", opt.url);
    if g.verbose {
        phase!("debug", "output={} jobs={}", opt.output.display(), opt.jobs);
    }
    step!("fetching");
    ok!(opt.output.join("file.csv").display());
    summary! {
        done:   "Download complete",
        "url"    => paint(CYAN, &opt.url),
        "output" => paint(CYAN, &opt.output.display().to_string()),
        section,
        "size"   => paint(YELLOW, &format_bytes(43_100)),
        "time"   => paint(DIM, "320ms"),
    }
}

fn upload(g: &Global, opt: UploadOpt) {
    header!(
        "mytool",
        env!("CARGO_PKG_VERSION"),
        "batch file processor",
        "fast and parallel"
    );
    phase!("upload", "{} → {}", opt.file.display(), opt.remote);
    if g.verbose {
        phase!("debug", "compress={}", opt.compress);
    }
    step!("uploading");
    ok!(opt.remote.as_str());
    summary! {
        done:   "Upload complete",
        "file"   => paint(CYAN, &opt.file.display().to_string()),
        "remote" => paint(CYAN, &opt.remote),
    }
}

fn net_download(g: &Global, opt: NetDownloadOpt) {
    header!(
        "mytool",
        env!("CARGO_PKG_VERSION"),
        "batch file processor",
        "fast and parallel"
    );
    phase!("net-download", "{} (timeout: {}s)", opt.url, opt.timeout);
    if g.verbose {
        phase!("debug", "using network stack");
    }
    step!("fetching");
    ok!("./data/file.bin");
    summary! {
        done:  "Download complete",
        "url"  => paint(CYAN, &opt.url),
        "time" => paint(DIM, "120ms"),
    }
}

fn net_ping(g: &Global) {
    header!(
        "mytool",
        env!("CARGO_PKG_VERSION"),
        "batch file processor",
        "fast and parallel"
    );
    phase!("ping", "checking connectivity...");
    if g.verbose {
        phase!("debug", "sending ICMP");
    }
    summary! {
        done:      "Reachable",
        "latency"  => paint(OK, "12ms"),
    }
}

fn status(g: &Global) {
    header!(
        "mytool",
        env!("CARGO_PKG_VERSION"),
        "batch file processor",
        "fast and parallel"
    );
    phase!("status", "checking...");
    if g.verbose {
        phase!("debug", "reading config");
    }
    summary! {
        done:      "All systems operational",
        "version"  => paint(OK, env!("CARGO_PKG_VERSION")),
        "config"   => paint(DIM, &g.config.as_deref()
                        .map(|p| p.display().to_string())
                        .unwrap_or_else(|| "default".into())),
    }
}

examples/mini_cargo.rs (line 716)

fn cmd_build(opt: &BuildOpt, global: &Global) {
    let mode = if opt.release { "release" } else { "dev" };
    phase!("compile", "Compiling packages in {} mode", mode);
    if let Some(ref e) = opt.example {
        phase!("target", "example = {e}");
    }
    if let Some(ref b) = opt.bin {
        phase!("target", "bin = {b}");
    }
    if let Some(ref t) = opt.target {
        phase!("target", "target = {t}");
    }
    if let Some(ref f) = opt.features {
        phase!("features", "{f}");
    }
    fake_compile(opt.jobs);
    ok!("target/debug/mini_cargo");
    summary! {
        done: "Build finished",
        "mode"    => paint(OK,     mode),
        "jobs"    => paint(DIM,    &opt.jobs.to_string()),
        "verbose" => paint(DIM,    &global.verbose.to_string()),
    }
}

fn cmd_run(opt: &RunOpt, global: &Global) {
    let mode = if opt.release { "release" } else { "dev" };
    phase!("compile", "Compiling in {} mode", mode);
    if let Some(ref e) = opt.example {
        phase!("run", "example = {e}");
    }
    if let Some(ref b) = opt.bin {
        phase!("run", "bin = {b}");
    }
    if let Some(ref f) = opt.features {
        phase!("features", "{f}");
    }
    fake_compile(4);
    phase!("running", "Running `target/{}/...`", mode);
    summary! {
        done: "Run complete",
        "mode"   => paint(OK, mode),
        "quiet"  => paint(DIM, &global.quiet.to_string()),
    }
}

fn cmd_add(opt: &AddOpt, _global: &Global) {
    let kind = if opt.dev {
        "dev-dependency"
    } else if opt.build {
        "build-dependency"
    } else {
        "dependency"
    };
    phase!("resolve", "Resolving {} `{}`", kind, opt.crate_name);
    if let Some(ref f) = opt.features {
        phase!("features", "enabling: {f}");
    }
    if opt.dry_run {
        phase!("dry-run", "would write to Cargo.toml (dry run)");
    } else {
        phase!("update", "Updating Cargo.toml");
        phase!("lock", "Updating Cargo.lock");
    }
    summary! {
        done: "Dependency added",
        "crate" => paint(CYAN, &opt.crate_name),
        "kind"  => paint(DIM,  kind),
    }
}

fn cmd_remove(opt: &RemoveOpt, _global: &Global) {
    phase!("remove", "Removing `{}` from Cargo.toml", opt.crate_name);
    summary! {
        done: "Dependency removed",
        "crate" => paint(CYAN, &opt.crate_name),
    }
}

fn cmd_new(opt: &NewOpt, _global: &Global) {
    let kind = if opt.lib { "library" } else { "binary" };
    let name = opt
        .name
        .as_deref()
        .or_else(|| opt.path.file_name()?.to_str())
        .unwrap_or("my-package");
    phase!("create", "Creating {} package `{}`", kind, name);
    phase!("edition", "edition = {}", opt.edition);
    if let Some(ref v) = opt.vcs {
        phase!("vcs", "initializing {} repo", v);
    }
    ok!(opt.path.display());
    summary! {
        done: "Package created",
        "name"    => paint(CYAN, name),
        "kind"    => paint(DIM,  kind),
        "edition" => paint(DIM,  &opt.edition),
    }
}

fn cmd_init(opt: &InitOpt, _global: &Global) {
    let dir = opt
        .path
        .as_deref()
        .unwrap_or_else(|| std::path::Path::new("."));
    let kind = if opt.lib { "library" } else { "binary" };
    phase!(
        "init",
        "Initializing {} package in `{}`",
        kind,
        dir.display()
    );
    if let Some(ref v) = opt.vcs {
        phase!("vcs", "initializing {} repo", v);
    }
    summary! {
        done: "Package initialized",
        "dir"     => paint(CYAN, &dir.display().to_string()),
        "edition" => paint(DIM,  &opt.edition),
    }
}

fn cmd_test(opt: &TestOpt, _global: &Global) {
    let mode = if opt.release { "release" } else { "dev" };
    phase!("compile", "Compiling test targets in {} mode", mode);
    if let Some(ref f) = opt.filter {
        phase!("filter", "running tests matching `{f}`");
    }
    if let Some(ref f) = opt.features {
        phase!("features", "{f}");
    }
    fake_compile(4);
    step!("running {} test thread(s)", opt.test_threads);
    eprintln!();
    eprintln!(
        "   {}  test result: {}. {} passed; 0 failed",
        paint(DIM, "│"),
        paint(OK, "ok"),
        paint(OK, "42"),
    );
    eprintln!();
    summary! {
        done: "Tests passed",
        "mode"    => paint(OK,     mode),
        "threads" => paint(DIM,    &opt.test_threads.to_string()),
        "passed"  => paint(OK,     "42"),
        "failed"  => paint(DIM,    "0"),
    }
}

fn cmd_check(opt: &CheckOpt, _global: &Global) {
    phase!("check", "Checking package");
    if opt.all_targets {
        phase!("targets", "checking all targets");
    }
    if let Some(ref f) = opt.features {
        phase!("features", "{f}");
    }
    if let Some(ref t) = opt.target {
        phase!("target", "{t}");
    }
    fake_compile(4);
    summary! { done: "Check passed" }
}

fn cmd_clean(opt: &CleanOpt, _global: &Global) {
    let mode = if opt.release { "release" } else { "debug" };
    phase!("clean", "Removing target/{}", mode);
    if let Some(ref p) = opt.package {
        phase!("package", "{p}");
    }
    summary! {
        done: "Clean complete",
        "mode" => paint(DIM, mode),
    }
}

fn cmd_metadata(opt: &MetadataOpt, _global: &Global) {
    phase!("metadata", "Resolving dependency graph");
    if opt.no_deps {
        phase!("filter", "excluding transitive dependencies");
    }
    eprintln!();
    eprintln!(
        "   {}  {{\"packages\":[...],\"workspace_root\":\"{}\"}}",
        paint(DIM, "│"),
        paint(DIM, "."),
    );
    eprintln!();
    summary! {
        done:    "Metadata output",
        "version" => paint(DIM, &opt.format_version.to_string()),
    }
}

fn cmd_update(opt: &UpdateOpt, _global: &Global) {
    if let Some(ref c) = opt.crate_name {
        phase!("update", "Updating `{}`", c);
    } else {
        phase!("update", "Updating all dependencies");
    }
    if opt.dry_run {
        phase!("dry-run", "would update Cargo.lock (dry run)");
    }
    summary! { done: "Lock file updated" }
}

fn cmd_info(opt: &InfoOpt, _global: &Global) {
    phase!("fetch", "Fetching info for `{}`", opt.crate_name);
    if let Some(ref v) = opt.version {
        phase!("version", "showing v{v}");
    }
    eprintln!();
    eprintln!(
        "   {}  {} v1.0.0",
        paint(DIM, "│"),
        paint(CYAN, &opt.crate_name)
    );
    eprintln!(
        "   {}  {}",
        paint(DIM, "│"),
        paint(DIM, "A well-known Rust crate (emulated)")
    );
    eprintln!(
        "   {}  https://crates.io/crates/{}",
        paint(DIM, "│"),
        opt.crate_name
    );
    eprintln!();
    summary! {
        done: "Info retrieved",
        "crate" => paint(CYAN, &opt.crate_name),
    }
}

fn cmd_import(opt: &ImportOpt, _global: &Global) {
    phase!("read", "Reading CSV manifest `{}`", opt.file.display());
    if opt.dry_run {
        phase!("dry-run", "would update Cargo.toml (dry run)");
    } else {
        phase!("update", "Updating Cargo.toml");
    }
    summary! {
        done: "Import complete",
        "file" => paint(CYAN, &opt.file.display().to_string()),
    }
}

// ── Helpers ───────────────────────────────────────────────────────────────────

fn fake_compile(jobs: usize) {
    let pkgs = ["proc-macro2", "quote", "syn", "serde", "cli-ui"];
    step!("compiling {} packages ({} jobs)", pkgs.len(), jobs);
    eprintln!();
    for pkg in &pkgs {
        eprintln!(
            "   {}  {} {}",
            paint(DIM, "│"),
            paint(DIM, "Compiling"),
            paint(CYAN, pkg),
        );
    }
    eprintln!();
}

examples/validation.rs (line 330)

fn main() {
    let opt = Opt::parse();
    let input = opt.resolved_alt_input();
    let output = opt.resolved_alt_output();
    let start = std::time::Instant::now();

    header!(
        "processor",
        env!("CARGO_PKG_VERSION"),
        "process and transform data files",
        "fast, validated, reliable"
    );

    let fmt = if opt.json {
        "json"
    } else if opt.csv {
        "csv"
    } else if opt.toml {
        "toml"
    } else {
        "default"
    };

    phase!("init", "reading {}", input.display());
    phase!("cfg", "format={} jobs={} port={}", fmt, opt.jobs, opt.port);

    if opt.dry_run {
        phase!("mode", "dry run — nothing will be written");
    }
    if opt.verbose {
        phase!("debug", "verbose output enabled");
    }
    if opt.sign {
        phase!("auth", "signing enabled, key={:?}", opt.key);
    }
    if opt.no_auth {
        phase!("auth", "authentication disabled");
    }
    if let Some(ref p) = opt.pattern {
        phase!("filter", "pattern: {p}");
    }
    if let Some(ref n) = opt.worker_name {
        phase!("worker", "name: {n}");
    }
    if let Some(ref p) = opt.profile {
        phase!("profile", "{p}");
    }
    if let Some(ref e) = opt.example {
        phase!("example", "{e}");
    }
    if let Some(ref b) = opt.bin {
        phase!("bin", "{b}");
    }

    if !opt.dry_run {
        let out = output.join(format!("result.{fmt}"));
        ok!(out.display());
    }

    let elapsed = start.elapsed().as_millis();
    summary! {
        done:    "Processing complete",
        "input"  => paint(CYAN, &input.display().to_string()),
        "output" => paint(CYAN, &output.display().to_string()),
        section,
        "format" => paint(OK,     fmt),
        "jobs"   => paint(OK,     &opt.jobs.to_string()),
        "port"   => paint(YELLOW, &opt.port.to_string()),
        "time"   => paint(DIM,    &format!("{elapsed}ms")),
    }
}

examples/mytool.rs (line 195)

fn main() {
    // parse() handles --help, --version, --completions,
    // unknown flags, and missing positionals automatically
    let opt = Opt::parse();

    // resolved_alt_input() generated from conflicts_with = "input"
    let input = opt.resolved_alt_input();
    let output = opt.resolved_alt_output();
    let start = std::time::Instant::now();

    // bail! prints error and exits 1
    if !input.exists() {
        bail!("input path does not exist: {}", input.display());
    }

    header!(
        "mytool",
        env!("CARGO_PKG_VERSION"),
        "batch file processor",
        "fast and parallel"
    );

    phase!("init", "scanning {}", input.display());
    phase!(
        "scan",
        "found {} remote · {} local   jobs: {}",
        8,
        3,
        opt.jobs
    );

    if opt.dry_run {
        phase!("mode", "dry run — nothing will be written");
    }
    if !opt.include.is_empty() {
        phase!("filter", "include: {}", opt.include.join(", "));
    }
    if !opt.exclude.is_empty() {
        phase!("filter", "exclude: {}", opt.exclude.join(", "));
    }

    // ── remote files ──────────────────────────────────────────────────
    let remote: &[(&str, &str, usize)] = &[
        ("https://example.com/data.csv", "./data/data.csv", 43_100),
        ("https://example.com/ref.json", "./data/ref.json", 8_500),
        (
            "https://example.com/schema.json",
            "./data/schema.json",
            2_300,
        ),
        ("https://cdn.example.com/lib.js", "./js/lib.js", 128_000),
        (
            "https://cdn.example.com/style.css",
            "./css/style.css",
            12_400,
        ),
    ];

    step!("downloading remote files");
    let pb = Progress::new(remote.len());
    let mut errors = 0usize;
    for (url, local, bytes) in remote {
        // simulate one failure
        if url.contains("lib.js") {
            pb.fail("file", url, "connection timeout");
            errors += 1;
        } else {
            pb.ok("file", "remote", url, local, *bytes);
        }
    }
    pb.finish();

    // ── local files ───────────────────────────────────────────────────
    let local: &[(&str, &str, usize)] = &[
        ("config.toml", "./cfg/config.toml", 1_200),
        ("rules.yaml", "./cfg/rules.yaml", 3_400),
        ("README.md", "./README.md", 8_800),
    ];

    step!("copying local files");
    let pb2 = Progress::new(local.len());
    for (src, dst, bytes) in local {
        pb2.ok("file", "local", src, dst, *bytes);
    }
    pb2.finish();

    // ── nested operations ─────────────────────────────────────────────
    step!("resolving references in style.css");
    substep!(
        "https://fonts.example.com/Inter.woff2",
        "./fonts/Inter.woff2"
    );
    substep!(
        "https://fonts.example.com/JetBrains.woff2",
        "./fonts/JetBrains.woff2"
    );

    // ── write ─────────────────────────────────────────────────────────
    if !opt.dry_run {
        step!("writing output");
        ok!(output.join(format!("result.{}", opt.format)).display());
    }

    // ── summary ───────────────────────────────────────────────────────
    let remote_ok = remote.len() - errors;
    let total_files = remote_ok + local.len();
    let total_bytes: usize = remote
        .iter()
        .filter(|(u, _, _)| !u.contains("lib.js"))
        .map(|(_, _, b)| b)
        .chain(local.iter().map(|(_, _, b)| b))
        .sum();

    let input_val = paint(CYAN, &input.display().to_string());
    let output_val = paint(
        BOLD,
        &output
            .join(format!("result.{}", opt.format))
            .display()
            .to_string(),
    );
    let files_val = format!(
        "{} total · {} errors",
        paint(OK, &total_files.to_string()),
        paint(if errors > 0 { ERR } else { DIM }, &errors.to_string())
    );
    let size_val = paint(YELLOW, &format_bytes(total_bytes));
    let time_val = paint(DIM, &format!("{}ms", start.elapsed().as_millis()));

    if errors == 0 {
        summary! {
            done:    "All files processed",
            "input"  => input_val,
            "output" => output_val,
            section,
            "files"  => files_val,
            "size"   => size_val,
            "time"   => time_val,
        }
    } else {
        summary! {
            warn:    "Completed with errors",
            "input"  => input_val,
            "output" => output_val,
            section,
            "files"  => files_val,
            "size"   => size_val,
            "time"   => time_val,
        }
    }
}

examples/prompt.rs (line 178)

fn main() -> cli_ui::prompt::Result<()> {
    header!(
        "prompt",
        env!("CARGO_PKG_VERSION"),
        "interactive prompt showcase",
        "all prompt types"
    );

    intro("Set up a new project");

    // ── 1. Single select with per-option hints ────────────────────────────────
    let template = select("How would you like to start your new project?")
        .option("basic", "A basic, helpful starter project")
        .option("blog", "Use blog template")
        .hint("Markdown-based blog with RSS feed support")
        .option("docs", "Use docs (Starlight) template")
        .hint("Documentation site with search and sidebar")
        .option("minimal", "Use minimal (empty) template")
        .hint("Just a Cargo.toml and src/lib.rs — nothing else")
        .run()?;

    // ── 2. Text input with validation ─────────────────────────────────────────
    let dir = text("Where should we create your new project?")
        .default("./my-app")
        .placeholder("e.g. ./my-project")
        .hint("Use a relative or absolute path")
        .validate(|s| {
            if s.starts_with('.') || s.starts_with('/') {
                Ok(())
            } else {
                Err("path must start with . or /".into())
            }
        })
        .run()?;

    // ── 3. Multi select with per-option hints ─────────────────────────────────
    let features = multiselect("Which features would you like to enable?")
        .option("ts", "TypeScript")
        .hint("JavaScript with syntax for types")
        .option("tailwind", "Tailwind CSS")
        .hint("A utility-first CSS framework")
        .option("react", "React")
        .hint("A JavaScript library for building user interfaces")
        .option("vue", "Vue")
        .hint("The Progressive JavaScript Framework")
        .option("eslint", "ESLint")
        .hint("Find and fix problems in your JavaScript code")
        .run()?;

    // ── 4. Grouped multiselect ────────────────────────────────────────────────
    let tools = groupmultiselect("Select development tools:")
        .group("Frontend")
        .item("TypeScript")
        .hint("JavaScript with syntax for types")
        .item("ESLint")
        .hint("Find and fix problems in your JS code")
        .item("Prettier")
        .hint("An opinionated code formatter")
        .group("Backend")
        .item("Node.js")
        .hint("JavaScript runtime built on V8")
        .item("Express")
        .hint("Fast, unopinionated web framework")
        .item("Prisma")
        .hint("Next-generation ORM for Node.js")
        .group("Testing")
        .item("Jest")
        .hint("Delightful JavaScript testing framework")
        .item("Cypress")
        .hint("End-to-end testing for the modern web")
        .item("Vitest")
        .hint("Vite-native unit testing framework")
        .run()?;

    // ── 5. Autocomplete ───────────────────────────────────────────────────────
    let pkg = autocomplete("Search for a UI package:")
        .option("astro", "Astro")
        .hint("The web framework for content-based sites")
        .option("react", "React")
        .hint("A JavaScript library for building user interfaces")
        .option("vue", "Vue")
        .hint("The Progressive JavaScript Framework")
        .option("svelte", "Svelte")
        .hint("Cybernetically enhanced web apps")
        .option("angular", "Angular")
        .hint("Platform for building mobile & desktop web apps")
        .option("solid", "SolidJS")
        .hint("Simple and performant reactivity for building UIs")
        .option("qwik", "Qwik")
        .hint("HTML-first framework with instant interactivity")
        .placeholder("Type to search...")
        .max_items(5)
        .run()?;

    // ── 6. Confirm ────────────────────────────────────────────────────────────
    let git = confirm("Initialize a new git repository?")
        .default(true)
        .run()?;

    // ── 7. Secret ─────────────────────────────────────────────────────────────
    let _token = secret("Enter your API token (optional)")
        .allow_empty(true)
        .hint("Leave empty to skip — you can set it later in .env")
        .run()?;

    // ── 8. Single-keypress select ─────────────────────────────────────────────
    let action = select_key("Apply changes?")
        .option('y', "Yes, apply")
        .hint("write to disk")
        .option('n', "No, abort")
        .hint("discard everything")
        .option('d', "Diff first")
        .hint("preview the changes")
        .run()?;
    log::info(format!("you chose: {} ({})", action.key, action.label));

    note(
        "What happens next",
        "We'll scaffold your project, install dependencies,\nand initialise git if you opted in.",
    );

    // ── 9. Spinner + tasks runner ─────────────────────────────────────────────
    let s = spinner();
    s.start("Resolving dependencies");
    std::thread::sleep(std::time::Duration::from_millis(700));
    s.message("Downloading 42 packages");
    std::thread::sleep(std::time::Duration::from_millis(700));
    s.stop("Resolved 42 packages");

    // ── 10. Progress bar ──────────────────────────────────────────────────────
    // Filled/empty bar rendered inside a spinner line. Advance in a loop
    // (or from a worker thread) with `.advance(step, Some(message))`.
    let pb = progress().style(ProgressStyle::Heavy).size(30).max(50);
    pb.start("Downloading assets");
    for i in 1..=50 {
        std::thread::sleep(std::time::Duration::from_millis(30));
        let msg = format!("asset {i}/50");
        pb.advance(1, Some(msg));
    }
    pb.stop("Downloaded 50 assets");

    tasks(vec![
        Task::new("Compiling", |s| {
            std::thread::sleep(std::time::Duration::from_millis(400));
            s.message("crate cli-ui");
            std::thread::sleep(std::time::Duration::from_millis(400));
            Some("Compiled in 0.8s".into())
        }),
        Task::new("Running tests", |_| {
            std::thread::sleep(std::time::Duration::from_millis(500));
            Some("All 12 tests passed".into())
        }),
    ]);

    log::success("Project ready");
    outro("Happy hacking!");

    let _ = prompt::Result::<()>::Ok(());

    // ── Summary ───────────────────────────────────────────────────────────────
    let feat_str = if features.is_empty() {
        paint(DIM, "none")
    } else {
        paint(OK, &features.values().join(", "))
    };

    let tool_str = if tools.is_empty() {
        paint(DIM, "none")
    } else {
        paint(OK, &tools.values().join(", "))
    };

    summary! {
        done:        "Project configured",
        "template"   => paint(CYAN,   template.value()),
        "directory"  => paint(CYAN,   &dir),
        section,
        "features"   => feat_str,
        "tools"      => tool_str,
        "ui package" => paint(CYAN,   pkg.value()),
        section,
        "git"        => paint(if git { OK } else { DIM }, if git { "yes" } else { "no" }),
    }

    Ok(())
}