docs

The command line

One command, pullmark, that hands files and folders to the app. Built for humans in a terminal and for agents and scripts that want to put a document in front of you.

Installing the command

How you got PullMark decides how you get the command:

• Homebrew — already installed; the cask links pullmark into your brew prefix.
• DMG — open Settings (⌘,) → General and click Install pullmark Command…; it links the command into /usr/local/bin (you may be asked to authorize).
• Source checkout — make install-cli (add BIN_DIR=~/bin to choose where).

No install needed for the basics, either way — open -a PullMark README.md ~/notes does the same through macOS itself.

Usage

pullmark                     # launch (or focus) PullMark
pullmark <path> ...          # open files and/or folders
pullmark --diff <path> ...   # open files as rendered diffs vs HEAD
pullmark --diff=<ref> <path> ...
                             # … vs a branch, tag, or commit
pullmark --diff=<r1>..<r2> <path> ...
                             # the file at two refs, both frozen
pullmark --diff-with=<file> <path> ...
                             # … vs another file on disk
pullmark -h, --help          # the built-in reference
pullmark --version           # print the app version

What opening does

The rules are deliberately boring, so a script can rely on them:

• Files land in the sidebar's Open Files section as pinned entries, and the last file passed is shown.
• Folders — including git worktrees — become Locations: browsable trees of the Markdown files inside.
• Already running? Everything opens in the frontmost window. A second app instance is never started.
• Relative paths resolve against your current directory; ~ works as usual.
• A path that doesn't exist aborts the whole command with a message and exit code 1 — nothing half-opens.

Worktrees, and pointing at one file

Pass a folder and a file together and you get both behaviors at once: the folder opens as a Location, the file opens pinned and displayed. That's the whole recipe for "open this worktree and show me this doc":

$ pullmark ~/wt/feature ~/wt/feature/docs/plan.md

The worktree's tree lands in Locations (with its branch chip, since a worktree is just a git checkout), plan.md is pinned in Open Files and rendered. Right-click it and choose Reveal in Location to jump to where it sits in the tree. This works the same when the Location was already open — opening a file that lives inside it never creates a duplicate world, just a working-set entry.

Order doesn't matter for the folder/file pairing, but the last file passed is the one displayed, so put the document you want on screen last.

Rendered diffs from the shell

--diff opens each file comparing — its working contents against the last commit, shown as the same rendered, word-level diff pull requests get. --diff=<ref> compares against a branch, tag, or commit SHA instead. It's the shell door into the app's Compare feature (the toolbar's clock-and-chevron button), and the fastest answer to "what did the agent just do to this document":

$ pullmark --diff docs/plan.md            # what the last edits changed
$ pullmark --diff=main README.md          # current file vs main
$ pullmark --diff=v1.0..main README.md    # between two revisions, both frozen
$ pullmark --diff-with=old.md new.md      # two files, old.md the baseline
$ pullmark --diff ~/wt/feature ~/wt/feature/docs/plan.md
                                          # a worktree, plan.md diffed

Folders passed alongside still open as Locations, and every form has an in-app twin in the toolbar's Compare menu (including Compare Revisions… and Compare with File…). Because --diff and --diff-with are flags, never subcommands, a file that happens to be named diff always just opens.

Exit codes

Examples

$ pullmark README.md                      # read one file
$ pullmark ~/notes                        # browse a folder
$ pullmark docs specs/design.md           # a Location plus one document
$ pullmark ~/wt/feature docs/plan.md      # a worktree, showing one doc
$ pullmark --diff docs/plan.md            # what the last edits changed
$ pullmark -- --weird-filename.md         # -- ends option parsing

Notes for agents

If you're wiring PullMark into an agent or a script:

• The command returns as soon as macOS accepts the open — it does not wait for the app to render.
• Repeating an open is idempotent: an already-open file or folder is selected, not duplicated.
• Everything lands in the frontmost window by design, so a human watching one window sees each open arrive there.
• After editing a document, pullmark --diff <file> is the one-line way to put what you changed in front of the human — rendered, with the changed words highlighted.