This page describes Calíope 1.8, the version I am building right now. 1.7 is on the App Store for the Mac, iPad, iPhone, Apple Watch, Apple TV and Apple Vision Pro. The changelog says which version each feature landed in.
Adds an “Open in Calíope” button to every topic. It only works with the app installed.
Read .md, .sql, .json, .csv, .rtf and text files without opening an editor.
Where it is: Workspace › Tools › File Previewer
The File Previewer shows the contents of a local file interpreted by its extension: Markdown (.md) renders as a document, SQL (.sql) with syntax highlighting and line numbers, JSON (.json) re-indented and coloured, CSV (.csv, .tsv) as a table, rich text (.rtf) as a document, and plain text (.txt, .log) exactly as it is.
It is a read-only tool: it does not edit, does not save and does not run anything. To write and run queries there is the SQL Editor; to work with local SQLite databases, the SQLite Editor.
It works without a connection to any server and shows one file at a time, with a list of recent files.
Pick a file from disk or reopen it from the recents list.
Press Open… and pick any supported file: .md, .sql, .json, .csv, .tsv, .rtf, .txt or .log. The file is added to Recent, shown on the tool's start screen, which keeps the last eight.
Calíope stores a persistent permission for each recent file, so you can reopen it after quitting the app without hunting for it again. If the file is moved or deleted, the recent entry stops opening it and you just pick it again with Open….
Close releases the file and stops watching it for changes.
On the Mac, Quick Look — the eye button, or the space bar — shows the file in the system viewer, which also opens what the previewer does not interpret: PDFs, images, office documents.
You can also open it from outside Calíope. On the Mac, from the Finder with Open With › Calíope, or with a double-click if Calíope is the default app for that kind of file. On iPad and iPhone, by sharing it from the Files app and choosing Calíope. A .sql opened this way goes to the SQL Editor, not here, and a SQLite, DuckDB or Parquet file goes to the SQLite Editor or the DuckDB Editor. If the session in front of you doesn't offer this tool, the file opens in Open offline.
Rendering covers headings from # to ######; paragraphs with bold, italic, inline code, strikethrough and links; ordered and unordered lists, with nesting; checklists - [ ] and - [x]; block quotes >; horizontal rules; pipe tables; and fenced code blocks. When a block is tagged sql, it is highlighted just like a .sql file.
Deliberately left out: images are never downloaded — their alternative text is shown instead —, embedded HTML is not interpreted and front matter at the top is skipped.
Headings are announced to VoiceOver as headings and all the text scales with Dynamic Type.
Rich text files are read as a document, with their structure intact.
An .rtf file — what TextEdit, Word or Pages write when they export — is shown as a document, not as markup. Headings, lists with their nesting and numbering, bold, italic, underline, strikethrough, links, paragraph alignment and monospaced runs are all kept.
What is not applied is the document's typography: not the typeface, not the point sizes, not the colours. Calíope supplies those, exactly as it does for Markdown, so the text scales with Dynamic Type and reads as well in light theme as in dark. You are reminded of this at the foot while the file is open.
Heading levels are inferred from the font size relative to the document itself: the largest is level 1, the next one level 2, and so on. An RTF file declares no hierarchy anywhere, so that is all there is to go on.
Out of scope: .rtfd packages are not opened — they are a folder, not a file — and embedded images and objects are not shown; if the document carries any, you are told how many at the foot.
Syntax highlighting and line numbers, no execution.
.sql files are shown in a monospaced font, with line numbers and syntax highlighting: query, schema definition, control, functions, types, window and procedural keywords, plus string literals, numbers, --, # and /* … */ comments, and backtick-quoted identifiers.
There is no run button, and that is the point: the previewer never opens a connection. If you want to run the contents, open them in the SQL Editor.
Above 500 KB highlighting is switched off and the file is shown as plain text; a note at the bottom says so.
Re-indented JSON, CSV as a table, logs as they are.
JSON (.json) is re-indented with two spaces per level and coloured: keys, text, numbers and true/false/null. The order of the keys is the file's own — nothing is reordered — and if the content is not valid JSON, the previewer says so at the bottom and still shows what it could read. Above 2 MB formatting is switched off and the file is shown exactly as it is on disk.
CSV (.csv, .tsv) is shown as a table with row numbers and a fixed header. The separator is detected — comma, semicolon, tab or pipe — and named at the bottom; quoted fields, doubled quotes and line breaks inside a field are respected. Up to 10,000 rows and 64 columns are drawn, and any trim is stated. It does not sort and does not filter: it is a viewer, not a data grid.
Plain text (.txt, .log, and any unrecognised extension) is shown as it is, monospaced and with line numbers. Lines longer than 2,000 characters are split so they can be drawn, and the ↳ marker means a continuation of the line above.
Objects and arrays fold: the triangle in the margin hides the container and leaves a summary —[…] or {…}— with the number of members; the two header buttons fold and unfold the whole file. Empty containers already come on a single line.
Highlighted matches, a count, and jumps between them.
⌘F opens the search bar, as does the magnifier button in the header. It searches plain text, no regular expressions, and only over what was read: if the file was cut off at 5 MB, the notice above says so and the rest has not been looked at.
Matches are painted over the content without hiding the syntax highlighting, and the selected one uses a stronger shade. Return and ⌘G go to the next one, ⇧⌘G to the previous one, and the count in the bar says which one you are on. The Aa button matches case. Esc closes the bar.
It works on every type: in CSV the cell lights up and its row is marked; in Markdown and rich text, the text inside the block —in code blocks the match is counted and jumped to, but not lit up, because they keep their own highlighting—; and in JSON, a match hidden inside a folded container unfolds it when you jump to it. Up to 5,000 matches are counted; beyond that the bar shows a +.
The view updates on its own when the file changes on disk.
While the file is open, Calíope watches its path. If you save it from another program, the view updates on its own — with an Updated indicator for a few seconds — and keeps your reading position. You can also force it with Reload.
Watching survives atomic saves, the kind TextEdit, Xcode or vim do by replacing the file instead of rewriting it: it keeps refreshing after the second and third save.
If the file disappears, the tool says so without treating it as an error: deleting a file is not a failure.
Limits: for a large file the first 5 MB are read — the header says how much is being shown —, SQL highlighting is switched off above 500 KB, JSON formatting above 2 MB, and a CSV is drawn up to 10,000 rows and 64 columns. Every trim is stated at the bottom of the view.
How it detects the encoding of a text file, where it shows it, and what it says when it cannot read one.
Where it is: Workspace › Tools › File Previewer
To read a text file, the File Preview first looks for a byte order mark (UTF-8, or UTF-16 in either byte order). Without one, it treats the file as binary if it finds a NUL byte near the start; otherwise it tries UTF-8, then the system’s detection, then Windows-1252 and ISO-8859-1, in that order. The encoding it finds is shown in the header next to the file type.
A binary file, or one it cannot decode, shows “Binary file or unsupported text encoding.”. When a large file is cut, the cut falls on a clean character boundary.
See the tables and first rows of a SQLite, DuckDB or Parquet file without opening Calíope.
With Calíope installed, the system's Quick Look shows a SQLite database, a DuckDB database or a Parquet file as tables, without opening the app. On the Mac, select the file in the Finder and press the space bar. On iPad and iPhone, tap it in the Files app, or preview it from any app that shows files.
At the top come the file's name, its kind, its size and the engine that read it, then the list of tables, each with its number of rows and its columns with their types. Below, the first 20 rows of each table, one after another; in a database with more than ten tables only the first ten show rows and the rest stay in the list. A Parquet file is a single table, with the types DuckDB infers. In a DuckDB database, views, sequences and macros are listed under Other objects, without rows.
The preview never writes: it creates no file next to the original and doesn't change its modification date. That's why a SQLite database in WAL mode shows what is saved in the main file, and says so: changes still in its -wal file don't appear.
On the Mac, a TSV file also opens as a table. A CSV file is shown by macOS itself, as a table without types; on iPad and iPhone the system shows CSV as a table and TSV as text. To see them as a table with types, open them in Calíope.
Nothing can be edited or queried here: to run SQL, open the file in Calíope with the button the system shows above the preview. Apple Vision Pro doesn't load other apps' previews, so there the system shows its own card with the file's name and size.
Keywords: quick look, space bar, finder, files, preview, sqlite, duckdb, parquet, tsv, csv
About three seconds per preview, large files, encrypted databases and pending writes.
A preview has about three seconds to read the file. It reads first what tells you the most —the list of tables, then the rows of the first ones, then the row counts— and if time runs out it stops there and says so: open the file in Calíope to see the rest. A database with hundreds of tables shows its whole list in under a second; with thousands, the preview stops at those three seconds with the list complete and the rows of the first ten.
Size alone isn't a problem, because only the first rows are read: a 2 GB SQLite file opens in a couple of seconds. What isn't counted is a TSV file larger than 50 MB on the Mac: it shows Rows not counted and its first 20 rows.
When a file can't be read, the preview says why instead of staying blank:
- an encrypted SQLite database, or a file that isn't a database;
- on the Mac, a DuckDB database whose .wal file still holds writes: open it in Calíope to finish writing it;
- a damaged file: the preview shows the reason the engine gives;
- a database with no tables says so.
Calíope itself opens a DuckDB database with pending writes normally: on the Mac only the preview can't apply them, because the system only lets it read the file it is given. On iPad and iPhone, from the Files app, the preview does read the .wal file and shows the database with those writes.
Keywords: quick look, limit, time, large, encrypted, wal, damaged, rows not counted