Docs

Use VXO.

Everything VXO does, for people and for AI agents. The same page is plain Markdown at /docs.md.

Read as Markdown

VXO is a file viewer for macOS. It opens documents, spreadsheets, code, logs of any size, archives and images in milliseconds, keeps them current as they change on disk, and never modifies a file or runs anything inside one.

This page is written for people and for AI agents alike. The same text is at /docs.md as plain Markdown, and /llms.txt lists every resource.

  • Version: 0.5.0 · macOS 12 or later · Apple silicon
  • Free for personal use. Commercial use needs a license (pricing).

Install

One command

curl -fsSL https://vxo.fiftyseven.is/install.sh | sh

The script downloads VXO, checks its SHA-256, copies VXO.app to /Applications (or ~/Applications when /Applications is not writable), and links the vxo command into ~/.local/bin. Read it first if you like: /install.sh.

By hand

  1. Download VXO-0.5.0.zip and unzip it.
  2. Drag VXO.app to Applications and open it once.
  3. This build is not notarized by Apple yet. macOS will say it cannot check VXO: open System Settings, Privacy & Security, and click Open Anyway. Or, in Terminal: xattr -dr com.apple.quarantine /Applications/VXO.app.
  4. Optional, for the vxo command: ln -s /Applications/VXO.app/Contents/MacOS/vxo-cli ~/.local/bin/vxo.

From source

With Rust installed from rustup.rs: make install puts VXO in Applications and vxo in ~/.local/bin. make default makes VXO the default app for every format it reads.

Open files

  • Double-click a file in Finder (after make default, or Open With > VXO), or drop files on a VXO window.
  • From Terminal, vxo FILE opens the file as a new tab in the VXO window you already have, or starts VXO. It returns at once.
  • A folder opens with a sidebar. Arrow keys in the sidebar preview each file; Enter opens it.
  • Opening a file that already has a tab switches to that tab.
  • VXO keeps running when you close its last window, like Preview, so the next open is instant. Quit with ⌘Q; ⌥⌘Q quits and brings your windows back next time.

Pipe output into VXO

Anything a command prints can stream into a VXO tab:

kubectl logs -f api | vxo
npm test 2>&1 | vxo
git log -p | vxo
curl -s https://api.example.com/items | vxo

The tab opens as soon as the first bytes arrive and follows the end while the command runs. Output that starts with { or [ is shown as JSON, and a diff as a diff, with colour. vxo - reads stdin explicitly. The stream is kept in $TMPDIR/vxo-stdin/ and removed after a day. Ctrl-C stops the stream; the tab keeps what arrived.

Command line

CommandWhat it does
vxo FILE...Open each file as a tab in the front window (starts VXO if needed)
vxo --new FILEOpen in a new window
vxoA new window on the current folder
CMD | vxo, vxo -Stream stdin into a tab
vxo --serve [--port N] PATHHeadless: print VXO ready URL and serve the full viewer to any browser on this Mac
vxo --report [DAYS]Summarise the local usage log (default 30 days)
vxo --version, vxo --helpVersion, usage

--serve binds to 127.0.0.1 only, and the URL carries a random token that every request must present.

Keys

KeyAction
⇧⌘OOpen Quickly: fuzzy search under the folder, recent files first
⌘OOpen panel
[ ]Previous, next file in the folder
⌘T, ⌘W, ⇧⌘TNew tab, close tab, reopen the closed tab
⌃⇥, ⇧⌘] ⇧⌘[Next, previous tab
⌘F or /, then ⌘G or nFind as you type, then next
⌘L or :Go to line
⇧⌘L, ⌥ZOutline, wrap long lines
⌘CCopy the selection; cells as TSV; an image as an image
⌘PPrint
⇧⌘EExtract an archive with Archive Utility
⌥⌘R, ⌥⌘CShow in Finder, copy the path
⌘RReload from disk
j k, d u, space, g GScroll, half page, page, top, bottom
xAny file as hex
tNext theme
?Every key

Every command is also in the menu bar, so Help's search field finds any of them by name.

Formats

FamilyExtensions
Text and codetxt, log, and about a hundred code extensions; any size; highlighting for 17 language families
Markdownmd, markdown, mdx; GitHub-flavoured, math (KaTeX), diagrams (mermaid)
PDFpdf, with page thumbnails
Worddocx, doc, rtf, odt
Spreadsheetsxlsx, xlsm, xlsb, xls, ods, csv, tsv; Excel number formats, frozen panes, formulas
PowerPointpptx, ppt and their variants
Apple iWorknumbers, pages, key
Imagespng, jpg, gif, webp, heic, tiff, avif, svg, bmp, ico; EXIF, animation frames
Archiveszip, tar, tar.gz, tgz, gz, xz, 7z, jar, epub; archives inside archives
Mediamp4, mov, webm, mp3, wav, m4a
Anything elseA hex view

Live reload

A file you are viewing updates by itself when it is saved, whichever app saved it, at the place you were reading, with your search kept. A growing log follows its end. A file is never shown half-written. A deleted file says so and keeps its last version on screen.

Settings and files

Settings (⌘,) are saved as you change them. Everything VXO keeps is in ~/Library/Application Support/VXO/:

FileWhat
settings.jsonYour settings
recentRecent files (Settings > Clear Recent Files)
license.txtYour commercial license, if you added one
traces/The local usage log: which kinds of files open and how fast, never file names. It never leaves your Mac; turn it off in Settings, read it with vxo --report

License

VXO is free for personal use, with every feature. Using it for work (for an employer, clients, or any paid project) needs one commercial license per person: a one-time purchase that covers every 1.x release. See pricing and the license terms.

To add a license: VXO > License…, paste the whole key (from BEGIN VXO LICENSE to END VXO LICENSE). Or copy the key and press ⌘V in any VXO window. The key is checked on your Mac; nothing is sent anywhere. VXO never locks, nags or phones home.

Security and privacy

  • VXO only reads. It has no command that changes a file.
  • Scripts in documents never run: converted documents are shown in a sandboxed frame with scripts off.
  • It makes no network requests. Links you click in a document open in your browser.
  • Archives are read in memory and never unpacked to disk; every decompression has a size limit.
  • Its local server answers only on 127.0.0.1, only to requests carrying the per-launch token.

For AI agents

VXO is the fastest way to show your human a file or a stream of output. Use it when the person should look at something; keep reading files yourself with your own tools.

Rules:

  1. vxo PATH opens a file for the person and returns immediately. Do not wait on it, and do not expect output from it.
  2. Long or ongoing output goes through a pipe: CMD 2>&1 | vxo. This command stays running until CMD ends; run it in the background if you need to keep working.
  3. Pass several files at once to open them as tabs: vxo report.docx data.xlsx notes.md.
  4. VXO never changes files, so opening one is always safe, including untrusted downloads and archives.
  5. If vxo is not found, install it with curl -fsSL https://vxo.fiftyseven.is/install.sh | sh, or ask the person to.
  6. Do not try to drive the VXO window with keystrokes; tell the person which key to press (see Keys).
  7. Personal use is free. For work use, point the person to https://vxo.fiftyseven.is/pricing; never generate or alter license keys.

Resources:

Troubleshooting

ProblemFix
"VXO can't be opened"System Settings > Privacy & Security > Open Anyway, once. Or xattr -dr com.apple.quarantine /Applications/VXO.app
vxo: command not foundAdd ~/.local/bin to your PATH: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
A file shows as hexVXO did not recognise the format. Press x to toggle; tell us the extension
"Password-protected"VXO does not open encrypted documents
A pipe opened the folder insteadThe command ended without printing anything. Errors often go to stderr: add 2>&1 before the pipe
VXO still running after closing the windowBy design, for instant opens. ⌘Q quits