---

Features

| Feature | Description | | --------------------------------------- | ---------------------------------------------------------------------------------------------- | | 100+ Font Styles | Classic terminal, retro gaming, modern pixel, decorative, and monospace fonts. All free for commercial and personal use. | | Multi-Format Export | Export to PNG, TXT, Go, JavaScript, Python, Rust, and Bash. PNG exports with transparent background. | | Advanced Text Effects | Color gradient effects (horizontal & vertical), shadow effects (horizontal & vertical), and text scaling (0.5×–4×).| | Rich Color Support | 14 vibrant predefined UI colors that can be combined with gradients. The library and CLI also accept any hex color for unlimited possibilities.| | Alignment & Spacing | Adjust character, word, line spacing, and per-character manual kerning. Align text left, center, or right. | | Smart Typography | Automatic and custom kerning options, descender detection and alignment. | | Powerful CLI Tool | Render text quickly with extended options for fonts, colors, spacing, and effects. | | Standalone Go Library | A simple, self-contained API with type-safe enums for effortless programmatic ANSI text rendering. |

---

Quick Start

# 1. Clone the repository
git clone https://github.com/paulilaaso/bit
cd bit
2. Install dependencies
go mod tidy
3. Build the interactive UI
go build -o bit ./cmd/bit
4. Start creating!
./bit

---

Installation

Quick Install (Linux/macOS)

curl -sfL https://raw.githubusercontent.com/paulilaaso/bit/main/install.sh | sh

This installs bit to /usr/local/bin. The binary works in two modes:

• Interactive UI: Run bit with no arguments
• CLI mode: Run bit [options] <text> to render directly

Manual Installation

Download the latest release for your platform from the Releases page.

Available for:

• Linux (x86_64, arm64)
• macOS (x86_64, arm64)
• Windows (x86_64, arm64)

Extract and install:

# Linux/macOS
tar -xzf bit*Linuxx8664.tar.gz
sudo mv bit /usr/local/bin/
Windows (PowerShell)
Expand-Archive bit*Windowsx8664.zip
Move bit.exe to your PATH

Build from Source

Prerequisites: Go 1.25+

# Clone repository
git clone https://github.com/paulilaaso/bit
cd bit
Build the binary
make build
Or manually
go build -o bit ./cmd/bit

[!NOTE]

Fonts are embedded using go:embed, ensuring the binaries are fully self-contained.

---

Usage

Running Bit

# Start interactive UI
bit
CLI mode - quick render
bit "Hello World"
CLI mode - with options
bit -font ithaca -color 31 "Red Text"
List all fonts
bit -list
Load custom font or directory of fonts (along with built-in fonts)
bit -load ./myfont.bit
bit -load ./fonts/
Show help
bit -help

Interactive UI - Keyboard Controls

| Key Binding | Action Description | | --------------------------------------- | ---------------------------------------------------------------------------------------------- | | ← → / h l | Navigate between the 6 main control panels | | ↑ ↓ / k j | Adjust values in the currently selected panel or navigate text rows in multi-line mode | | Tab | Access sub-modes within panels | | Enter | Activate/deactivate text input mode for editing | | r | Randomize font, colors, and gradient settings for instant inspiration | | e | Enter export mode to save your creation in various formats | | Esc | Quit the application and return to terminal |

Control Panels

The UI features 6 main control panels with sub-modes accessible via Tab key:

1. 🔴 Text Input Panel (3 modes)

- Text Input Mode: Enter and edit text with multi-line support - Press ↓ to create new row - Press ↑↓ to navigate between rows - Cursor positions are tracked per-row - The row count is shown in label when editing multiple rows - Text Kerning Mode: Fine-tune letter spacing at the cursor position - Press ←→ or h/l to move the cursor through the current row - Press ↑↓ or k/j to increase/decrease spacing by one pixel - The current manual kerning value is shown in the label as +1, -2, etc. - Text Alignment Mode: Choose Left, Center, or Right alignment

2. 🟢 Font Selection Panel

- Browse through 100+ available bitmap fonts - Shows "Font X/XXX" in label - Fonts are lazy loaded on first use for memory efficiency

3. 🔵 Spacing Panel (3 modes)

- Character Spacing: 0 to 10 pixels between characters - Word Spacing: 0 to 20 pixels for multi-word lines - Line Spacing: 0 to 10 pixels for multi-line text layout

4. 🟡 Color Panel (3 modes)

- Text Color 1: Primary text color (14 ANSI colors) - Text Color 2: Gradient end color - Gradient auto-enables when different from Text Color 1 - Shows "None" when same as Text Color 1 - Gradient Direction: Up-Down, Down-Up, Left-Right, Right-Left

5. 🟣 Text Scale Panel

- Four scale options: 0.5x, 1x, 2x, 4x - Uses ANSI-aware scaling algorithm - Handles half-pixel characters correctly

6. ⚫ Shadow Panel (3 modes)

- Horizontal Shadow: -5 to 5 pixels (← or →) - Shows "Off" at 0 position - Vertical Shadow: -5 to 5 pixels (↑ or ↓) - Shows "Off" at 0 position - Shadow Style: Light (░), Medium (▒), Dark (▓) - Visual preview shows actual ANSI character repeated

[!WARNING]

If shadows are enabled with half-pixel characters, a warning appears in the title bar. The library automatically disables shadows in this case to prevent visual artifacts.

CLI Mode

The bit binary includes a powerful CLI mode for quick text rendering:

Basic Commands

# Render text with default settings
bit "Hello"
List all available fonts
bit -list
Use specific font and color (ANSI code)
bit -font ithaca -color 31 "Red"
Use specific font and color (hex code)
bit -font ithaca -color "#FF0000" "Red"
Gradient text with ANSI codes
bit -font dogica -color 31 -gradient 34 -direction right "Gradient"
Gradient text with hex codes
bit -font dogica -color "#FF0000" -gradient "#0000FF" "Gradient"
Text with shadow
bit -font larceny -color 94 -shadow -shadow-h 2 -shadow-v 1 "Shadow"
Scaled text
bit -font pressstart -color 32 -scale 1 "2X"
Aligned text
bit -font gohufontb -color 93 -align right "Go\nRight"
Inline custom kerning: \+ adds space, \- removes space
bit "H\+el\+lo W\-orld"

CLI Options

| Flag | Description | Values | | ----------------- | ------------------------------ | --------------------------------------- | | -font | Font name to use | Any available font name (default: first font) | | -color | Text color | ANSI codes (30-37, 90-96) or hex (#FF0000) | | -gradient | Gradient end color | ANSI codes (30-37, 90-96) or hex (#0000FF) | | -direction | Gradient direction | down, up, right, left | | -char-spacing | Character spacing | 0 to 10 | | -word-spacing | Word spacing | 0 to 20 | | -line-spacing | Line spacing | 0 to 10 | | -scale | Text scale factor | -1 (0.5x), 0 (1x), 1 (2x), 2 (4x) | | -shadow | Enable shadow effect | true/false | | -shadow-h | Shadow horizontal offset | -5 to 5 | | -shadow-v | Shadow vertical offset | -5 to 5 | | -shadow-style | Shadow style | 0 (light), 1 (medium), 2 (dark) | | -align | Text alignment | left, center, right | | -list | List all available fonts | - |

Available Colors

| Code | Color | Preview | Code | Color | Preview | | -------- | --------------- | ----------- | -------- | ---------------- | ----------- | | 30 | Black | | 90 | Gray | | | 31 | Red | | 91 | Bright Red | | | 32 | Green | | 92 | Bright Green | | | 33 | Yellow | | 93 | Bright Yellow | | | 34 | Blue | | 94 | Bright Blue | | | 35 | Magenta | | 95 | Bright Magenta | | | 36 | Cyan | | 96 | Bright Cyan | | | 37 | White | | 97 | Bright White | |

[!TIP]

The CLI and library support any hex color (e.g., -color "#FF5733"), providing unlimited color possibilities beyond the ANSI palette.

---

Library

Bit includes a powerful standalone Go library (ansifonts) that's completely independent of the TUI. The library can be imported into any Go project without any TUI dependencies.

Quick Library Example

package main
import ( 	"fmt" 	"github.com/paulilaaso/bit/ansifonts" )
func main() { 	// Load a font 	font, err := ansifonts.LoadFont("ithaca") 	if err != nil { 		panic(err) 	}
// Advanced rendering with options 	options := ansifonts.RenderOptions{ 		CharSpacing:            3, 		WordSpacing:            3, 		LineSpacing:            1, 		TextColor:              "#FF0000", 		GradientColor:          "#0000FF", 		UseGradient:            true, 		GradientDirection:      ansifonts.LeftRight, 		Alignment:              ansifonts.CenterAlign, 		ScaleFactor:            1.0, 		ShadowEnabled:          true, 		ShadowHorizontalOffset: 2, 		ShadowVerticalOffset:   1, 		ShadowStyle:            ansifonts.MediumShade, 	}
// Validate options before rendering (optional - render functions validate automatically) 	if err := options.Validate(); err != nil { 		fmt.Printf("Invalid options: %v\n", err) 		return 	}
rendered := ansifonts.RenderTextWithOptions("Hello", font, options) 	for _, line := range rendered { 		fmt.Println(line) 	} }

[!TIP]

See the ansifonts library documentation for detailed API reference and examples.

---

Font Collection

The project includes 100+ carefully curated bitmap fonts embedded in the binary.

Fonts are stored as .bit files (JSON format) containing:

{
  "name": "Font Name",
  "author": "Author Name",
  "license": "License Type",
  "characters": {
    "A": ["line1", "line2", ...],
    "B": ["line1", "line2", ...],
    ...
  }
}

[!NOTE]

Each font file contains a license field indicating its specific license terms. All fonts are under permissive open-source licenses, which allow free usage, modification, and distribution for both personal and commercial purposes.

Export Formats

The interactive UI supports exporting your creations to:

| Format | Extension | Description | |--------|-----------|-------------| | PNG | .png | PNG image with transparent background | | TXT | .txt | Plain text with ANSI codes stripped | | Go | .go | Go source code with embedded ANSI strings | | JavaScript | .js | JavaScript array with console.log display function | | Python | .py | Python list with print function | | Rust | .rs | Rust vector with println! macro | | Bash | .sh | Bash script with echo -e for ANSI support |

All exports include:

• Properly escaped ANSI sequences
• Language-specific string literals
• Ready-to-run code

PNG exports preserve the exact appearance of your terminal art with transparent backgrounds.

---

Acknowledgments

• Font Authors: Thank you to all the original font creators whose work is included.
• Charm: For the excellent TUI framework.
• Go Community: For the robust standard library and tooling.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.