https://github.com/bgreenwell/doxx
Expose the contents of .docx files without leaving your terminal. Fast, safe, and smart — no Office required!
https://github.com/bgreenwell/doxx
cli docx msword render rust terminal tui
Last synced: 7 days ago
JSON representation
Expose the contents of .docx files without leaving your terminal. Fast, safe, and smart — no Office required!
- Host: GitHub
- URL: https://github.com/bgreenwell/doxx
- Owner: bgreenwell
- License: mit
- Created: 2025-08-16T18:48:24.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2025-09-28T01:33:58.000Z (15 days ago)
- Last Synced: 2025-09-28T03:19:24.667Z (15 days ago)
- Topics: cli, docx, msword, render, rust, terminal, tui
- Language: Rust
- Homepage: https://bgreenwell.github.io/doxx/
- Size: 5.51 MB
- Stars: 2,959
- Watchers: 9
- Forks: 71
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- stars - bgreenwell/doxx - Expose the contents of .docx files without leaving your terminal. Fast, safe, and smart — no Office required! (Rust)
- awesome-ratatui - doxx - Document viewer for Microsoft Word files. (💻 Apps / 🌌 Other)
- awesome-markdown - doxx - 一款为终端设计的 `.docx` 文件查看器，它可以将 Word 文档的内容在命令行中美观渲染，并支持 **Markdown**、CSV、JSON 等多种格式导出，为开发者和命令行用户提供高效的文件浏览、搜索和数据提取体验。     (其他工具 / 命令行工具)
- my-awesome-github-stars - bgreenwell/doxx - Expose the contents of .docx files without leaving your terminal. Fast, safe, and smart — no Office required! (Rust)
- StarryDivineSky - bgreenwell/doxx
README
# doxx 📄 
> `.docx` files in your terminal — no Microsoft Word required
[](https://github.com/bgreenwell/doxx/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
[](https://www.rust-lang.org/)
A fast, terminal-native document viewer for Word files. View, search, and export `.docx` documents without leaving your command line.
## Screenshots
Terminal image display
Color support
Smart tables with alignment
Lists and formatting
## 🎬 Demo
Mixed formatting with colors, bold, italic, underline, strikethrough and interactive navigation
## ✨ 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, ANSI-colored output
- **Terminal images** for Kitty, iTerm2, WezTerm 🖼️
- **Color support** — see Word document colors in your terminal
## 🚀 Installation
### Package managers
#### Homebrew (macOS/Linux)
```bash
brew install doxx
```
#### Cargo (cross-platform)
```bash
cargo install doxx
```
#### Arch Linux
```bash
pacman -S doxx
```
The AUR package is also available for the development version:
```bash
yay -S doxx-git
```
*Thanks to [@mhegreberg](https://github.com/mhegreberg) for creating and maintaining the AUR package!*
#### Nix (cross-platform)
```bash
nix profile install github:bgreenwell/doxx
```
*Thanks to [@bobberb](https://github.com/bobberb) for creating the Nix flake!*
#### Conda-Forge (cross-platform)
```bash
conda install doxx
```
or globally using [Pixi](pixi.sh):
```bash
pixi global install doxx
```
#### Scoop (Windows)
```bash
# Coming soon
scoop bucket add doxx https://github.com/bgreenwell/doxx-scoop
scoop install doxx
```
### Pre-built binaries
Download from [GitHub releases](https://github.com/bgreenwell/doxx/releases):
```bash
# 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
```bash
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
```bash
# 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
```bash
doxx [OPTIONS]
```
| Option | Description |
|--------|-------------|
| `` | 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 ` | Jump to specific page number on startup |
| `-s, --search ` | 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 ` | `markdown`, `text`, `csv`, `json`, `ansi` | Export document instead of viewing |
**Export examples:**
```bash
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
doxx document.docx --export ansi # ANSI-colored terminal output
```
**📊 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.
### ANSI export options
| Option | Values | Description |
|--------|--------|-------------|
| `-w, --terminal-width ` | Number | Set terminal width for formatting (default: $COLUMNS or 80) |
| `--color-depth ` | `auto`, `1`, `4`, `8`, `24` | Control color rendering depth |
**ANSI export examples:**
```bash
doxx document.docx --export ansi # Full color ANSI output
doxx document.docx --export ansi --color-depth 1 # Monochrome (no colors)
doxx document.docx --export ansi --color-depth 4 # 16 colors
doxx document.docx --export ansi --terminal-width 80 # Set terminal width
doxx report.docx --export ansi | less -R # Pipe to less with color support
```
**🌈 Color depth options:**
- `auto` - Auto-detect terminal capabilities
- `1` - Monochrome (no colors, formatting only)
- `4` - 16 colors (standard ANSI colors)
- `8` - 256 colors (extended ANSI palette)
- `24` - True color (16.7 million colors)
### Image options
| Option | Description |
|--------|-------------|
| `--images` | Display images inline in terminal (auto-detect capabilities) |
| `--extract-images ` | Extract images to specified directory |
| `--image-width ` | Maximum image width in terminal columns (default: auto-detect) |
| `--image-height ` | Maximum image height in terminal rows (default: auto-detect) |
| `--image-scale ` | Image scaling factor (0.1 to 2.0, default: 1.0) |
**Image examples:**
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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:
- **[docx-rs](https://crates.io/crates/docx-rs)** — Document parsing
- **[ratatui](https://crates.io/crates/ratatui)** — Terminal UI
- **[viuer](https://crates.io/crates/viuer)** — Image rendering
- **[unicode-segmentation](https://crates.io/crates/unicode-segmentation)** — Proper Unicode handling
## 🛠️ Development
```bash
# Build and test
cargo build --release
cargo test
# Run with sample document
cargo run -- tests/fixtures/minimal.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
## 💡 Inspiration
This project was inspired by [Charm](https://github.com/charmbracelet)'s [Glow](https://github.com/charmbracelet/glow) package — the beautiful terminal Markdown renderer that shows how terminal document viewing can be both powerful and elegant. Just as Glow brings rich Markdown rendering to your command line, doxx aims to do the same for Microsoft Word documents.
Thanks to the Charm team for the inspiration! ✨
## 📝 License
MIT License — see [LICENSE](LICENSE) file for details.
---
**Made for developers who live in the terminal** 🚀