^{Special thanks to:}

Warp, the intelligent terminal for developers

Available for MacOS, Linux, & Windows

---

Mcat

Parse, Convert and Preview files
In your Terminal

Installation • Examples • CHANGELOG

🚀 Installation

cargo install mcat

or ~

git clone https://github.com/Skardyy/mcat
cd mcat
cargo install --path ./crates/core

or prebuilt from the latest release

🤔 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)

• Pretty Terminal 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

• Static Image set when -o image and gives an image

• Interactive Image set when -o interactive 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

#------------------------------------#
#  View a documents in the terminal  #
#------------------------------------#

mcat resume.pdf
mcat project.docx -t monokai           # With a different theme
mcat "https://realpdfs.com/file.pdf"   # 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 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 -o interactive  # zoom and pan the image interactively in the terminal

#--------------------------#
#  What I use it most for  #
#--------------------------#

mcat ls                                # To find the image i was looking for
mcat . | scb                           # Selects files, concat them, and copy to clipboard ~ for AI prompts
mcat index.html -o image > save.png    # Render HTML into images

📦 Optional Dependencies

Mcat will continue working without them

Chromium (for rendering HTML 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

---

pdftocairo/pdftoppm (for rendering PDF to image)

---

1. Is included by default in most major distros
2. Windows users can install from poppler-windows
3. If not installed, mcat will fallback into converting the PDF to Markdown and then screenshot using chromium

---

FFmpeg (for videos)

---

1. If it's already on your machine 🫠.
2. Otherwise, you can install it with mcat --fetch-ffmpeg

---

⚙️ Configuring

Using Flags

---

the main flags for configuring are:

• --opts for inline image printing
• --ls-opts for the ls command

run mcat --help for full detail, and other flags.

---

Using Environment Variables

---

each variable mimicks its corresponding flag alternative.

• MCAT_ENCODER, Options: kitty,iterm,sixel,ascii. e.g. MCAT_ENCODER=kitty is the same as doing --kitty
• MCAT_PAGER, the full command mcat will try to pipe into.
• MCAT_THEME, same as the --theme flag
• MCAT_INLINE_OPTS, same as the --opts flag
• MCAT_LS_OPTS, same as the --ls-opts flag
• MCAT_SILENT, same as the --silent flag
• MCAT_NO_LINENUMBERS, same as the --no-linenumbers flag

---

🚧 Roadmap

• mcat.nvim: a neovim plugin to use mcat inside neovim

📎 License

MIT License