crossterm

Crossterm is a cross-platform terminal manipulation library with the following capabilities:

• Cursor Control: Move cursor (up, down, left, right, specific columns), set/get position, store/restore position, and hide/show cursor.
• Styled Output: Foreground/Background colors (16 base, 256 ANSI, RGB) and text attributes (bold, italic, etc.).
• Terminal Manipulation: Clear screen/lines, scroll, set terminal size, exit process, use alternate/raw screens, set title, and toggle line wrapping.
• Event Handling: Input events, Mouse events (press, release, position, button, drag), Terminal Resize events, and advanced modifier support (SHIFT, ALT, CTRL). Supports futures::Stream via the event-stream feature.

To use crossterm in your Rust project, add it to your Cargo.toml dependencies.

[dependencies]
crossterm = "0.27"

Before opening a pull request, run the required local checks. You can use just to run these conveniently if you have it installed.

Using Just

Install just and run:

• just to list available recipes
• just ci to run required checks for your current operating system

Manual Check Commands

If not using just, run these commands manually:

cargo fmt --all -- --check
cargo clippy --locked --all-targets --all-features -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --locked --all-features --no-deps
cargo test --locked --doc --all-features
cargo test --locked --all-targets --all-features -- --test-threads 1
cargo package --locked
cargo deny --locked check advisories licenses sources
actionlint
zizmor --offline --strict-collection .

Note: Tests run single-threaded (--test-threads 1) because they interact with process-wide terminal and environment state.

On Unix systems, test the following feature configurations to ensure compatibility:

cargo test --locked --lib -- --test-threads 1
cargo test --locked --lib --features serde -- --test-threads 1
cargo test --locked --lib --features event-stream,events -- --test-threads 1
cargo test --locked --lib --no-default-features -- --test-threads 1
cargo test --locked --lib --no-default-features --features events -- --test-threads 1
cargo test --locked --lib --no-default-features --features events,event-stream,use-dev-tty,bracketed-paste -- --test-threads 1

Ensure the library works with the minimum supported Rust version (1.85.0) without default features and with all public features:

rustup run 1.85.0 cargo check --locked --lib --no-default-features
rustup run 1.85.0 cargo check --locked --lib --all-features

To run the advisory Clippy check (which warns about lints likely to reach the next stable toolchain) locally, use:

rustup run beta cargo clippy --locked --all-targets --all-features -- -D warnings

To maintain consistency, follow these rules for code structure:

Import Order

Imports must be semantically grouped and ordered as follows, with an empty line between groups:

1. Standard library (use std::...)
2. External crates (use rand::...)
3. Current crate (use crate::...)
4. Parent module (use super::..)
5. Current module (use self::...)
6. Module declaration (mod ...)

Line Length Limits

• Code: 100 characters
• Comments in code: 120 characters
• Documentation: 120 characters

use crossterm_utils::{csi, write_cout, Result};

use crate::sys::{get_cursor_position, show_cursor};

use super::Cursor;

Windows builds require the windows feature. The crate rejects a bare --no-default-features build on Windows. Test with these configurations:

cargo test --locked --lib --no-default-features --features windows -- --test-threads 1
cargo test --locked --lib --no-default-features --features windows,events -- --test-threads 1

You can run the provided examples using cargo run --example. The examples cover various topics such as cursor manipulation, styling, event reading (including async), and using Crossterm over stderr with raw mode and alternate screens.

$ cargo run --example [file name]

Crossterm organizes terminal manipulation into several functional modules:

• cursor: Manage cursor visibility, appearance, and position (e.g., MoveTo, Show, Hide).
• style: Apply colors, attributes, and hyperlinks to text (e.g., SetForegroundColor, SetAttribute).
• terminal: Control terminal-wide settings like scrolling, clearing, and alternate screens (e.g., Clear, EnterAlternateScreen).
• event: Read keyboard and mouse events (requires events feature).
• clipboard: Interact with the system clipboard (requires osc52 feature).
• ansi_support: Check for ANSI support on Windows.