CASOON Open Source

One way for your CLI tools to talk.

runemark renders status lines, reports, error blocks and file-change previews with one colour policy: TTY-aware, NO_COLOR-compliant, plain when redirected. The crate and the npm package share the same Rust renderer.

cargonpm

cargo add runemark

npm install @casoon/runemark

MITcrates.ionpmRust 1.85+Node 20+

A terminal running cargo run --example hero_demo --features progress: a progress bar fills as four pages are audited, then a site audit report appears with its metrics, two accessibility findings and a next step.

required dependency (unicode-width): 1
prebuilt Node platforms: 5
minimum Rust version: 1.85
ecosystems, one renderer: 2

What it does

Semantic, not cosmetic
Callers say what a line means – success, warning, error, a verdict, a finding. runemark decides how it looks, so related tools read the same.
Predictable colour policy
Auto emits styles only to an interactive terminal, honours NO_COLOR and stays plain for TERM=dumb; Always and Never are explicit. Colour, symbols and hyperlinks can each be set on their own. Redirected output stays plain and deterministic.
Reports that fit the terminal
Compact or detailed, with metrics, grouped findings and next steps. Given a width, narrow layouts stack metrics and wrap messages with a hanging indent.
Menus when a prompt is not enough
An optional grouped menu with filtering, tabs and multi-pick for Unix terminals. It redraws on resize, never blocks without a terminal, and hands you a plain rendering to print instead.
Safe with untrusted text
Control characters in messages, paths and URLs are neutralised; hyperlinks are only emitted for http and https URLs and for file paths the tool resolves itself.

How it renders

One report, any width

Reports adapt to the terminal they're given, not to a fixed layout. Pass a known width and narrow terminals stack summary metrics and wrap finding messages with a hanging indent instead of truncating.

Verdict symbols survive NO_COLOR. A tone disappears without color; the verdict's own symbol does not — a failing metric still reads as failing piped to a file.
Compact or detailed, same data. The host CLI chooses detailLevel; runemark never asks for two separate report shapes. Compact output says how many findings it left out, and your tool words the pointer to the rest.
Determinism by construction. Identical input always walks the same path — no timing-dependent output, so fixtures can be committed and diffed.

Reports guide →Colour policy →

44 columns

⚠ Content audit

  Errors: 0
  Warnings: 4 (+2)
  Score: 94/100 (+5%)

● Navigation (2)
  - The main navigation contains more links
    than can be reached comfortably with a
    keyboard [ux/nav-size]
  - Two landmarks share the label "Menu", so
    screen reader users cannot tell them
    apart [a11y/landmark-label]

Generated at build time

All examples →

⚠ Site audit v1.2.0
  Scope warnings: History partial, 1 file skipped

  Errors: 0   Warnings: 4 (+2)   Score: 94/100 (+5%)

● Accessibility violations (2)
  - [QUICK WIN] Image missing alt attribute [a11y/img-alt] (high confidence)
    at 
    Remedy: Add an alt="…" description to the <img> tag.
  - Low contrast ratio on hero button [a11y/contrast]
    at 

Next steps:
  • Run the auto-fixer for formatting issues
    $ audit --fix

These terminals and the ones in the showcase are rendered by @casoon/runemark during the build – the same renderer as the crate. Only the animation at the top is a recording, of the hero_demo example.

site/src/showcase.ts

Quickstart

Three steps from install to consistent output. The full walkthrough lives in the documentation.

Add the crate or the npm package to your command-line tool.
Pick a colour mode – Auto is right for most tools.
Pass your own data to semantic lines, reports, error blocks or diffs.

Read the documentation

main.rsRust

use runemark::{ColorMode, Console, Tone, Verdict};

let console = Console::stdout(ColorMode::Auto);

println!("{}", console.paint(Tone::Title, "site audit"));
println!("{}", Verdict::Warning.render(console, "3 findings need review"));
println!("{}", console.paint(Tone::Muted, "Run with --details for every finding."));

audit.cjsNode

const { RunemarkConsole, renderReport } = require('@casoon/runemark')

const console = new RunemarkConsole({ color: 'auto' })
console.writeWarning('3 findings need review')

process.stdout.write(renderReport({
  schemaVersion: 1,
  title: 'Site audit',
  verdict: 'warning',
}, { width: process.stdout.columns }))

New in v0.10.0

Changelog →

Select: Item, Group and Hint are #[non_exhaustive], so build them with new and the builder methods. Item::id must be unique within a menu.
Console: Console::with_hyperlinks and hyperlinks_enabled switch OSC 8 hyperlinks independently of colour and symbols. They still follow the colour decision by default, so existing output is unchanged.
Reports: Report::with_details_hint changes or removes the "(use --details to view all)" text on a compact "more findings" line. The default text is unchanged.
API: DiffBlock, Location and Badge gain write_to for streaming to any writer.
Select: Home, End, PgUp and PgDn jump through the list, and keys typed before the menu opens are discarded.
Node: the console, render, error and diff options take stream: 'stdout' | 'stderr' to choose which stream color: 'auto' checks, and hyperlinks to switch OSC 8 links independently of colour.

Frequently asked questions

Do the Rust crate and the Node package produce identical output?

Yes. The npm package wraps the same Rust renderer through a native addon — there is one presentation layer, not a port kept in sync by hand.

Does runemark work on Windows?

Semantic output, color policy, reports and progress do. The optional select menu talks to the terminal directly through termios and is Unix-only — on Windows it reports Outcome::Unavailable and the caller falls back to render().

What does output look like under NO_COLOR or when piped to a file?

Plain and deterministic. Tones disappear, but a verdict's own symbol stays, so a failing metric still reads as failing without color.

How do I test the output of my CLI?

Render with ColorMode::Never for deterministic text, or strip the escape sequences from a coloured string with strip_ansi. assert_plain_snapshot! compares the plain result against an expected block, and the Node package renders the same bytes.

Can I turn off symbols or hyperlinks without turning off colour?

Yes. Colour, the symbol set and OSC 8 hyperlinks follow one decision by default and can each be overridden: Console::with_theme chooses Unicode or ASCII symbols, Console::with_hyperlinks switches links.

Does runemark parse my CLI arguments or define my report data?

No. It owns terminal presentation only — color policy, layout, semantic tones. Argument parsing, configuration, domain finding types and output formats like JSON or SARIF stay yours.

Consistent CLI output in three steps.

Read the quickstart

One way for your CLI tools to talk.

What it does

Semantic, not cosmetic

Predictable colour policy

Reports that fit the terminal

Menus when a prompt is not enough

Safe with untrusted text