From Source
cargo install mcator ~
git clone https://github.com/Skardyy/mcat
cd mcat
cargo install --path ./crates/corePrebuilt
follow the instructions at the latest release
Homebrew (MacOS/Linux)
brew install Skardyy/mcat/mcatAUR (Arch linux)
yay -S mcat-binWinget (Windows)
winget install skardyy.mcatAdvanced explanation
| Input |
|---|
Inputs can be:
- local file
- url
- 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.docxandfile.pdfinto 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 mdor when the stdout isn't the terminal (piped) -
Pretty Terminalis markdown with ANSI formatting, and is the default for any non video / image file. (the-cflag forces it) -
HTMLset when-o html-- only works for non image / video files -
Static Imageset when-o imageand gives an image -
Interactive Imageset when-o interactiveand launches an interactive view to zoom and pan the image in the terminal. -
Inline Displayset when-o inlineor-iand prints the content as image in the terminal
#------------------------------------#
# 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 imagesMcat will continue working without them
Chromium (for rendering HTML to image)
- Available by default on most Windows machines via Microsoft Edge.
- Also works with any installed Chrome, Edge, or Chromium.
- You can install it manually via
mcat --fetch-chromium
pdftocairo/pdftoppm (for rendering PDF to image)
- Is included by default in most major distros
- Windows users can install from poppler-windows
- If not installed, mcat will fallback into converting the PDF to Markdown and then screenshot using chromium
FFmpeg (for videos)
- If it's already on your machine.
- Otherwise, you can install it with
mcat --fetch-ffmpeg
Using Flags
the main flags for configuring are:
--optsfor inline image printing--ls-optsfor 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--kittyMCAT_PAGER, the full command mcat will try to pipe into.MCAT_THEME, same as the--themeflagMCAT_INLINE_OPTS, same as the--optsflagMCAT_LS_OPTS, same as the--ls-optsflagMCAT_SILENT, same as the--silentflagMCAT_NO_LINENUMBERS, same as the--no-linenumbersflagMCAT_MD_IMAGE, same as the--no-imagesflag
- mcat.nvim: a neovim plugin to use mcat inside neovim
MIT License
Thanks to all contributors
Thanks to all sponsors