Metadata-Version: 2.4
Name: officecat
Version: 0.2.1
Summary: View Office files in the terminal
Project-URL: Homepage, https://github.com/mubbie/officecat
Project-URL: Repository, https://github.com/mubbie/officecat
Project-URL: Issues, https://github.com/mubbie/officecat/issues
Author: Mubbie Idoko
License: MIT
License-File: LICENSE
Keywords: cli,csv,docx,office,pptx,terminal,viewer,xlsx
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: python-calamine>=0.2
Requires-Dist: python-docx>=1.0
Requires-Dist: python-pptx>=0.6
Requires-Dist: rich
Requires-Dist: textual>=0.50
Requires-Dist: typer>=0.9
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# officecat 🐱

[![PyPI](https://img.shields.io/pypi/v/officecat)](https://pypi.org/project/officecat/)
[![CI](https://github.com/mubbie/officecat/actions/workflows/ci.yml/badge.svg)](https://github.com/mubbie/officecat/actions/workflows/ci.yml)
[![Python](https://img.shields.io/pypi/pyversions/officecat)](https://pypi.org/project/officecat/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/mubbie/officecat/blob/main/LICENSE)

A CLI tool to view Office files in the terminal. Think `cat` but for `.docx`, `.pptx`, `.xlsx`, `.csv`, and `.tsv` files.

Every supported format is converted to markdown internally, then rendered through a single unified pipeline.

## Installation

```bash
pip install officecat
```

Or install from source:

```bash
git clone https://github.com/mubbie/officecat.git
cd officecat
pip install -e .
```

## Usage

```bash
officecat report.docx              # colored formatted output (default)
officecat budget.xlsx              # spreadsheet as markdown table
officecat slides.pptx              # presentation content
officecat data.csv                 # CSV and TSV
officecat report.docx --tui        # interactive full-screen viewer
officecat budget.xlsx | head       # plain text (auto-detected pipe)
officecat slides.pptx --json       # JSON output
officecat --version                # show version
officecat update                   # update to latest version
```

Files must be local. OneDrive/SharePoint files that are "cloud-only" (not synced) will fail to open. Right-click the file and choose "Always keep on this device" to sync it first.

### Output Modes

- **Rich** (default): Colored, formatted output to stdout. Works with `less -R`.
- **TUI** (`--tui`): Full-screen interactive viewer with scrolling.
- **Plain** (auto when piped, or `--plain`): Raw markdown for piping to `grep`, `head`, `awk`.
- **JSON** (`--json`): `{"source": "...", "markdown": "..."}` for scripting.

### Options

| Flag | Short | Description |
|---|---|---|
| `--tui` | `-t` | Interactive full-screen viewer |
| `--plain` | `-p` | Raw markdown text, no colors |
| `--json` | `-j` | JSON output |
| `--head N` | `-n N` | Show first N lines |
| `--sheet S` | `-s S` | Select sheet by name or 1-based index (xlsx only) |
| `--slide N` | | Show only slide N (pptx only) |
| `--headers N` | `-h N` | Promote row N as headers (xlsx/csv, default: 1, 0 to disable) |
| `--all` | `-a` | Disable the default 500-row cap |
| `--version` | `-v` | Show version |

### TUI Key Bindings

| Key | Action |
|---|---|
| `q` | Quit |
| `Up` / `Down` | Scroll |
| `PgUp` / `PgDn` | Page scroll |
| `Home` / `End` | Jump to top/bottom |

### Examples

```bash
# Quick view of a document
officecat report.docx

# Browse interactively
officecat report.docx --tui

# Specific sheet
officecat budget.xlsx --sheet "Q4 Summary"

# Specific slide
officecat deck.pptx --slide 3

# First 10 lines
officecat budget.xlsx --head 10

# JSON output
officecat report.docx --json | jq '.markdown'

# Pipe to grep
officecat data.xlsx --plain | grep "revenue"

# Self-update
officecat update
```

## Supported Formats

- Word (.docx): headings, paragraphs, lists, tables in document order
- PowerPoint (.pptx): slides, shapes, images, speaker notes, hidden slides
- Excel (.xlsx): all sheets, row cap, header promotion
- CSV (.csv): auto-delimited
- TSV (.tsv): tab-delimited

Legacy binary formats (`.doc`, `.ppt`, `.xls`) show a conversion hint.

## Known Limitations

- Files must be local. Remote/cloud-only files (OneDrive, SharePoint) need to be synced first.
- All content is rendered as markdown. Spreadsheet tables are markdown tables, not interactive grids.
- DOCX list detection is style-name-based and may miss custom list styles.
- PPTX grouped shapes and embedded tables show as placeholders.
- PPTX charts and SmartArt are not extracted.
- XLSX formulas show cached/computed values, not formula strings.
- Large spreadsheets are capped at 500 rows by default. Use `--all` to show everything.
- TUI enforces a 1000-line cap with `--all` for performance. Use `--plain` for full output.
- No decryption of password-protected files.
- Legacy binary formats (.doc, .ppt, .xls) are not supported.

## License

[MIT](LICENSE)
