doxx

Crates.iodoxx
lib.rsdoxx
version0.1.1
created_at2025-08-22 14:21:37.084937+00
updated_at2025-08-22 14:21:37.084937+00
descriptionTerminal document viewer for .docx files
homepagehttps://github.com/bgreenwell/doxx
repositoryhttps://github.com/bgreenwell/doxx
max_upload_size
id1806426
size4,122,220
Brandon Greenwell (bgreenwell)

documentation

https://github.com/bgreenwell/doxx#readme

README

doxx 📄

.docx files in your terminal — no Microsoft Word required

CI License: MIT Rust

A fast, terminal-native document viewer for Word files. View, search, and export .docx documents without leaving your command line.

Screenshots

Terminal image display
Terminal image display 		Color support
Color support
Smart tables
Smart tables with alignment 		Lists and formatting
Lists and formatting

✨ Features

  • Beautiful terminal rendering with formatting, tables, and lists
  • Fast search with highlighting 🔍
  • Smart tables with proper alignment and Unicode borders
  • Copy to clipboard — grab content directly from the terminal
  • Export formats — Markdown, CSV, JSON, plain text
  • Terminal images for Kitty, iTerm2, WezTerm 🖼️
  • Color support — see Word document colors in your terminal

🚀 Installation

Package managers

Homebrew (macOS/Linux)

# Add our tap (coming soon)
brew tap bgreenwell/doxx
brew install doxx

Cargo (cross-platform)

cargo install doxx

Scoop (Windows)

# Coming soon
scoop bucket add doxx https://github.com/bgreenwell/doxx-scoop
scoop install doxx

Pre-built binaries

Download from GitHub releases:

# macOS/Linux - automatic platform detection
curl -L https://github.com/bgreenwell/doxx/releases/latest/download/doxx-$(uname -s)-$(uname -m).tar.gz | tar xz
sudo mv doxx /usr/local/bin/

# Verify installation
doxx --version

Available platforms:

  • Linux: x86_64-unknown-linux-musl (statically linked)
  • macOS: x86_64-apple-darwin (Intel) and aarch64-apple-darwin (Apple Silicon)
  • Windows: x86_64-pc-windows-msvc

Build from source

git clone https://github.com/bgreenwell/doxx.git
cd doxx
cargo install --path .

# Or for development
cargo build --release

Requirements:

  • Rust 1.70+
  • System dependencies: libxcb (Linux only)

🎯 Usage

# View a document
doxx report.docx

# Search for content
doxx contract.docx --search "payment"

# Start with outline view
doxx document.docx --outline

# Export to different formats
doxx data.docx --export csv > data.csv
doxx report.docx --export markdown > report.md

# View with images (supported terminals)
doxx presentation.docx --images --export text

# Enable color rendering
doxx slides.docx --color

📋 Command Line Options

Basic options

doxx [OPTIONS] <FILE>
Option Description
<FILE> Input document file (.docx)
-h, --help Show help information
-V, --version Show version information

Viewing options

Option Description
-o, --outline Start with outline view for quick navigation
-p, --page <PAGE> Jump to specific page number on startup
-s, --search <TERM> Search and highlight term immediately
--force-ui Force interactive UI mode (bypass TTY detection)
--color Enable color support for text rendering

Export options

Option Values Description
--export <FORMAT> markdown, text, csv, json Export document instead of viewing

Export examples:

doxx report.docx --export markdown  # Convert to Markdown
doxx data.docx --export csv         # Extract tables as CSV (tables only!)
doxx document.docx --export text    # Plain text output
doxx structure.docx --export json   # Document metadata as JSON

📊 CSV export note: The CSV export extracts only tables from the document, ignoring all text content. Perfect for pulling structured data from business reports, research papers, or surveys for analysis in Excel, Python, or databases.

Image options

Option Description
--images Display images inline in terminal (auto-detect capabilities)
--extract-images <DIR> Extract images to specified directory
--image-width <COLS> Maximum image width in terminal columns (default: auto-detect)
--image-height <ROWS> Maximum image height in terminal rows (default: auto-detect)
--image-scale <SCALE> Image scaling factor (0.1 to 2.0, default: 1.0)

Image examples:

doxx presentation.docx --images                    # Show images inline
doxx document.docx --images --image-width 80       # Limit image width
doxx slides.docx --extract-images ./images/        # Save images to folder

⚠️ Image display notes:

  • --images currently works with --export text mode and shows placeholders in TUI

  • Supports iTerm2, Kitty, and WezTerm terminals

⌨️ Navigation

Key Action
↑/k Scroll up
↓/j Scroll down
o Toggle outline
s Search
c Copy to clipboard
h Help
q Quit

🔧 Why doxx?

Current terminal tools for Word documents:

  • docx2txt → Loses all formatting, mangled tables
  • pandoc → Complex chain, formatting lost
  • antiword → Only handles old .doc files

doxx gives you:

  • ✅ Rich formatting preserved (bold, italic, headers)
  • ✅ Professional table rendering with alignment
  • ✅ Interactive navigation and search
  • ✅ Multiple export formats for workflows
  • ✅ Terminal image display for modern terminals
  • ✅ Fast startup (50ms vs Word's 8+ seconds)

Perfect for developers, sysadmins, and anyone who prefers the terminal.

📊 Examples

Quick document analysis

# Get overview and search
doxx quarterly-report.docx
doxx --search "revenue"

# Extract tables for analysis
doxx financial-data.docx --export csv | python analyze.py

Copy workflows

# Review and copy sections
doxx meeting-notes.docx
# Press 'c' to copy current view to clipboard

# Copy search results
doxx specs.docx --search "requirements"
# Press F2 to copy results with context

Pipeline integration

# Extract text for processing
doxx notes.docx --export text | grep "action items"

# Get document structure
doxx report.docx --export json | jq '.metadata'

🏗️ Architecture

Built with Rust for performance:

🛠️ Development

# Build and test
cargo build --release
cargo test

# Run with sample document
cargo run -- tests/fixtures/sample.docx

📋 Roadmap

  • Image support in TUI via ratatui-image crate
  • Enhanced table support (merged cells, complex layouts)
  • Performance improvements for large documents
  • Hyperlink navigation
  • Custom themes

📝 License

MIT License — see LICENSE file for details.

Made for developers who live in the terminal 🚀

Commit count: 75

cargo fmt