davideaversa.it / scrivener-cli
A CLI to (readonly) query Scrivener project in textual form
scrivener cli
Star 0
Fork 0
Watch
Python 98%
HTML 2%
21 1 0
scriv
test_data
tests
.gitignore
AGENTS.md
LICENSE
pyproject.toml
README.md
uv.lock
README.md

Scrivener CLI #

Scrivener CLI (scrivcli) is a command-line interface to read Scrivener projects. It is strictly read-only: it never writes to, modifies, or locks project files.

Motivation #

Scrivener is my main writing application. However, its file format is obscure, relying on many conventions and RTF files. This isn’t a problem 90% of the time, but it can be. In an era where easy access to file content is valuable, this limitation feels significant.

For instance, suppose I have an automation that every day checks what scene I wrote and gives me a summary to inspire me to continue writing. Or I want to ask an LLM "what was the color of the shoes of Billy in the first chapter?". In those cases, I need a way to easily access the content of my Scrivener projects and, luckily, CLI are a great interface. Much more lightweight than spawning a MCP server.

Usage #

Requirements #

  • Python 3.12 or newer. No third-party dependencies are required.
  • On macOS, RTF is converted with the built-in textutil. Elsewhere, a built-in RTF stripper is used. For better results without textutil, install the optional portable extra, which adds striprtf.

Installation #

pip install -e .

# optional, for better RTF conversion without macOS textutil
pip install -e ".[portable]"

How to use #

Well, this CLI is mostly aimed at LLMs and they can easily figure out. But sometimes, it may be useful for humans as well.

The CLI at the moment support four main commands:

  • ls: list documents in a project
  • show: show the content of a document
  • meta: show metadata of a document
  • info: show information about a project

This is the format of the commands:

scrivcli ls <project.scriv> [--flat] [--ids] [--no-badges] [--text-only]
scrivcli show <project.scriv> <doc> [--raw]
scrivcli meta <project.scriv> <doc>
scrivcli info <project.scriv>

<doc> can be:

  • the document ID (a UUID on Mac projects, a number on Windows projects), which you can see by running ls with --ids;
  • a slash-path from the top of the binder, as printed by ls --flat, e.g. Draft/Chapter 1/Waking Up;
  • the exact title of the document (case-insensitive).

Untitled binder items are shown as (Untitled) and can be referenced the same way, e.g. Draft/(Untitled). If a title or path matches more than one item, the command fails and lists every candidate with its ID, so you can pick the one you want.

show --raw prints the document's RTF source exactly as it is stored on disk.

Supported projects #

  • Scrivener 2 and 3 on macOS: <Name>.scrivx, with each document in Files/Data/<UUID>/content.rtf and its synopsis in synopsis.txt.
  • Scrivener 1.x on Windows: project.scrivx, with each document in Files/Docs/<id>.rtf.

The format is detected automatically.

Running without installation #

You can run the CLI without installing it by using uv.

uv run scrivcli <command> <args>

# with the portable RTF converter
uv run --extra portable scrivcli <command> <args>

Or, from a checkout, with python -m scriv <command> <args>.