https://github.com/skardyy/mcat
Terminal image, video, and Markdown viewer
https://github.com/skardyy/mcat
ascii iterm kitty ls markdown sixel terminal-graphics
Last synced: about 1 month ago
JSON representation
Terminal image, video, and Markdown viewer
- Host: GitHub
- URL: https://github.com/skardyy/mcat
- Owner: Skardyy
- License: mit
- Created: 2025-04-14T12:27:49.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-04-11T12:50:25.000Z (about 2 months ago)
- Last Synced: 2026-04-11T14:20:51.539Z (about 2 months ago)
- Topics: ascii, iterm, kitty, ls, markdown, sixel, terminal-graphics
- Language: Rust
- Homepage:
- Size: 10.3 MB
- Stars: 1,242
- Watchers: 7
- Forks: 44
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Support: support.md
Awesome Lists containing this project
README
# Mcat
Parse, Convert and Preview files
**_In your Terminal_**
 
[Installation](#installation) • [Examples](#example-usage) • [CHANGELOG](./CHANGELOG.md)
## Installation
From Source
```sh
cargo install mcat
```
or ~
```sh
git clone https://github.com/Skardyy/mcat
cd mcat
cargo install --path ./crates/core
```
Prebuilt
follow the instructions at the [latest release](https://github.com/Skardyy/mcat/releases/latest)
Homebrew (MacOS/Linux)
```sh
brew install mcat
```
AUR (Arch linux)
```sh
yay -S mcat-bin
```
Winget (Windows)
```sh
winget install skardyy.mcat
```
## How it works
Advanced explanation
---
| Input |
| ----- |
Inputs can be:
1. local file
2. url
3. bytes from stdin
The type of each input is inferred automatically, and it continues through the pipeline until it reaches the output format the user requested.
| In the pipeline |
| --------------- |
For example, if the user runs:
```
mcat file.docx file.pdf -o inline
```
`mcat` will:
- Convert both `file.docx` and `file.pdf` into a single Markdown file
- Convert that Markdown into HTML
- Convert the HTML into an image
- Convert the image into an inline terminal image and print it
You can also start from the middle of the pipeline.
For example:
```
mcat file.html -o image > image.png
```
This starts at an HTML file and directly converts it into a PNG image.
| Explanation of the blocks |
| ------------------------- |
- **`Markdown`** - set when `-o md` or when the stdout isn't the terminal (piped)
- **`Markdown Viewer`** is markdown with ANSI formatting, and is the **default** for any non video / image file. (the `-c` flag forces it)
- **`HTML`** set when `-o html` -- only works for non image / video files
- **`PNG Image`** set when `-o image` and gives an image
- **`Interactive Viewer`** set when `-o interactive` or `-I` and launches an interactive view to zoom and pan the image in the terminal.
- **`Inline Display`** set when `-o inline` or `-i` and prints the content as image in the terminal
---
## Example Usage
```sh
#---------------------------------------#
# View documents with ANSI formatting #
# in the terminal #
#---------------------------------------#
mcat resume.typst
mcat project.docx -t monokai # With a different theme
mcat "https://realmdfm.com/file.md" # From a url
cat file.pptx | mcat # From stdin
mcat . # Select files interactively
#-----------------#
# Convert files #
#-----------------#
mcat archive.zip > README.md # Into Markdown
mcat f1.rs f2.rs -o html > index.html # Into HTML
mcat index.html -o image > page.png # Into image
#--------------------------#
# View Images and Videos #
# in the terminal #
#--------------------------#
mcat resume.pdf # Pdf
mcat img.png # Image
mcat video.mp4 # Video
mcat "https://giphy.com/gifs/..." # From a URL
mcat README.md -i # Converts to image and then shows it
mcat ls # ls command with images
mcat massive_image.png -I # zoom and pan the image interactively in the terminal
mcat document.pdf -I # view PDF rendered as images interactively
mcat img.png README.md -I # view multiple files as images interactively
#--------------------------#
# What I use it most for #
#--------------------------#
mcat ls # To find the image i was looking for
mcat . | pbcopy # Selects files, concat them, and copy to clipboard
mcat index.html -o image > save.png # Render HTML into images
mcat archive.zip # View the content of a zip file.
```
## Support
To see which file types support which features, see the table [here](./support.md).
## Optional Dependencies
> Mcat will continue working without them
Chromium (for rendering HTML/Markdown/Text to image)
---
1. Available by default on most Windows machines via Microsoft Edge.
2. Also works with any installed Chrome, Edge, or Chromium.
3. You can install it manually via `mcat --fetch-chromium`
---
FFmpeg (for videos)
---
1. If it's already on your machine.
2. Otherwise, you can install it with `mcat --fetch-ffmpeg`
---
---
Thanks to all contributors
