# VXO documentation

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](/docs.md) as plain Markdown, and [/llms.txt](/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](/pricing)).

## Install

### One command

```sh
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](/install.sh).

### By hand

1. Download [VXO-0.5.0.zip](/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](https://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:

```sh
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

| Command | What it does |
|---|---|
| `vxo FILE...` | Open each file as a tab in the front window (starts VXO if needed) |
| `vxo --new FILE` | Open in a new window |
| `vxo` | A new window on the current folder |
| `CMD \| vxo`, `vxo -` | Stream stdin into a tab |
| `vxo --serve [--port N] PATH` | Headless: 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 --help` | Version, usage |

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

## Keys

| Key | Action |
|---|---|
| ⇧⌘O | Open Quickly: fuzzy search under the folder, recent files first |
| ⌘O | Open panel |
| `[` `]` | Previous, next file in the folder |
| ⌘T, ⌘W, ⇧⌘T | New tab, close tab, reopen the closed tab |
| ⌃⇥, ⇧⌘] ⇧⌘[ | Next, previous tab |
| ⌘F or `/`, then ⌘G or `n` | Find as you type, then next |
| ⌘L or `:` | Go to line |
| ⇧⌘L, ⌥Z | Outline, wrap long lines |
| ⌘C | Copy the selection; cells as TSV; an image as an image |
| ⌘P | Print |
| ⇧⌘E | Extract an archive with Archive Utility |
| ⌥⌘R, ⌥⌘C | Show in Finder, copy the path |
| ⌘R | Reload from disk |
| `j` `k`, `d` `u`, space, `g` `G` | Scroll, half page, page, top, bottom |
| `x` | Any file as hex |
| `t` | Next theme |
| `?` | Every key |

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

## Formats

| Family | Extensions |
|---|---|
| Text and code | txt, log, and about a hundred code extensions; any size; highlighting for 17 language families |
| Markdown | md, markdown, mdx; GitHub-flavoured, math (KaTeX), diagrams (mermaid) |
| PDF | pdf, with page thumbnails |
| Word | docx, doc, rtf, odt |
| Spreadsheets | xlsx, xlsm, xlsb, xls, ods, csv, tsv; Excel number formats, frozen panes, formulas |
| PowerPoint | pptx, ppt and their variants |
| Apple iWork | numbers, pages, key |
| Images | png, jpg, gif, webp, heic, tiff, avif, svg, bmp, ico; EXIF, animation frames |
| Archives | zip, tar, tar.gz, tgz, gz, xz, 7z, jar, epub; archives inside archives |
| Media | mp4, mov, webm, mp3, wav, m4a |
| Anything else | A 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/`:

| File | What |
|---|---|
| `settings.json` | Your settings |
| `recent` | Recent files (Settings > Clear Recent Files) |
| `license.txt` | Your 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](/pricing) and the [license terms](/license).

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:

- This page as Markdown: [/docs.md](/docs.md)
- Index for language models: [/llms.txt](/llms.txt)
- A prompt to paste into your agent: [/agent-prompt.txt](/agent-prompt.txt)
- Installer: [/install.sh](/install.sh)

## Troubleshooting

| Problem | Fix |
|---|---|
| "VXO can't be opened" | System Settings > Privacy & Security > Open Anyway, once. Or `xattr -dr com.apple.quarantine /Applications/VXO.app` |
| `vxo: command not found` | Add `~/.local/bin` to your PATH: `echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc` |
| A file shows as hex | VXO 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 instead | The command ended without printing anything. Errors often go to stderr: add `2>&1` before the pipe |
| VXO still running after closing the window | By design, for instant opens. ⌘Q quits |
