Shortcuts and the Command Line
New in 1.3.
If you do the same things in Grasmere again and again, you can build them into your own shortcuts. Grasmere gives the Shortcuts app actions for its everyday work, such as opening or making a document, adding to today’s entry, searching, checking the Markdown and links, exporting, and publishing the website.
Because the shortcuts command in Terminal runs shortcuts, each of these is a command too. shortcuts run hands the work to the running app, which does it with the folder access it already has, and prints the result.
In Shortcuts
Open the Shortcuts app, make a new shortcut and search the actions for Grasmere. They’re listed together under Grasmere’s own category. Ten of them are in Spotlight and Siri too, with names like “Open a document in Grasmere”, “Search Grasmere” and “Check Markdown in Grasmere”.
Every action works on the project in the front window unless you tell it otherwise. Actions that take a document or a folder will also take a path to any project Grasmere has opened before, because it keeps permission to those folders. So a shortcut can work on a project that isn’t open. If Grasmere has never opened the folder, you get an error naming it. Open it once with File ▸ Open Folder and it’s reachable from then on.
Actions that take a document have two fields. Document is for a file from another action or from the shortcut’s input. Path is for something typed, either a path or a document’s name or path in the front project, so Low Water finds chapters/Low Water.md. Leave both empty to use the document open on the page. Where an action takes a project, give the folder’s path or a recent project’s name. Leave it empty for the front window’s project.
Results are plain values, so you can pass them from one action to the next. You get a path or a line of text, a file, or a list of lines, one per document or one per problem.
The actions
| Action | Takes | Returns |
|---|---|---|
| Open Document | Document or Path | The document’s path. Opens it in the front window, or its project if that isn’t open, or on its own. |
| Open Project | Folder: a path or a recent project’s name | The folder’s path. In the front window if it’s empty, else a new window. |
| New Document | Title; Folder (optional); Text (optional) | The new file, titled with a heading, opened if its project is in a window. |
| Save Web Page (new in 1.3) | Web Address; Project (optional) | The new document in the research folder: the page’s article as Markdown, as File ▸ Save Web Page saves it. A page with no article (or that can’t be fetched) is saved as its link; a page saved before isn’t saved again, and its document is returned. See Research. |
| Append to Today’s Entry | Text; Project (optional) | Today’s entry, with the text added as quick capture adds it (a paragraph starting with the time); the entry is made if need be. |
| Append to Document | Text; Document or Path | The document, with the text added at the end as a paragraph of its own: through the editor if it’s open with unsaved changes, else into the file. |
| Get Document Text | Document or Path (optional) | The Markdown, as it is in the editor if it’s open, else the file’s. |
| Search Documents | Query; Project (optional); Passages (on by default) | A line per matching document: its path, then : and the first matching passage. Turn Passages off for paths alone. |
| List Documents | Folder (optional): a project or a folder in one | The path of every Markdown document in it, subfolders included, ignored folders left out. |
| Today’s Entry Path | Project (optional); Make It (on by default) | Today’s entry’s path, made as ⌘T would unless Make It is off (then an error when there’s none). |
| Check Markdown | Document or Path (optional) | A line per problem, path:line: error: message or warning, from the same check as the margin’s Problems section, whether or not that setting is on. Links to headings are judged when the project is open in a window. |
| Check Links | Project (optional) | A line per link that leads nowhere, path:line: error: message: a missing document or picture, or a heading or passage that isn’t where the link says. |
| Export PDF | Document or Path (optional); Output (optional) | The PDF, as File ▸ Export as PDF makes it. Output is a file path or a folder; left empty, the PDF goes beside the document. |
| Export Word Document | The same | The .docx, as File ▸ Export as Word Document makes it. |
| Compile Folder to PDF | Folder (optional); Output (optional); Layout (Book or Manuscript); Title; Author | The PDF, a chapter per document, as File ▸ Publish to PDF makes it. |
| Publish Website | Project (optional); Site Folder (optional) | The site folder’s path, once the website is built (the action waits). The first build of a project doesn’t ask what will be published, as the menu does, so look at the site. |
| Get Current Document | The document open in the front window (from 1.0). | |
| Get Current Project Folder | The front window’s project folder, as a path (from 1.0). | |
| Save Current Document | Saves the front window’s document (from 1.0). | |
| Add to Today’s Entry | Text; Project (optional) | The same as Append to Today’s Entry, answering with a sentence rather than the file (from 1.0; kept for shortcuts that use it). |
Actions that change a document need the trial running or Grasmere bought, as the app itself does. If neither is true, the action says so. No action ever changes your settings.
From the command line
The shortcuts command runs a shortcut by name, as shortcuts run "<shortcut>". See man shortcuts for the rest. It runs a shortcut, not an action. So for each action you want in Terminal, make a one-step shortcut in the Shortcuts app, once. Add the Grasmere action and name the shortcut after it, “Check Markdown”, say. From then on it’s a command.
The shortcut’s input comes from -i (--input-path), either a file’s path or - for whatever’s piped in. To print the result, add -o - (--output-path), or write it to a file with -o <path>. Leave -o out and the result goes nowhere.
In the one-step shortcut, put Shortcut Input in the action’s field. Use the Document field when you’ll give a file with -i <path>. Use the Text, Path or Query field when you’ll pipe text in with -i -. A file sent to a text field arrives as its contents rather than its path, so if you want to give a path, pipe it in as text.
# Add a thought to today's entry in the front project
echo "a thought" | shortcuts run "Append to Today's Entry" -i - -o -
# Check a document's Markdown (Shortcut Input in the Document field)
shortcuts run "Check Markdown" -i ~/Notes/post.md -o -
# Search, a line per document
echo ferry | shortcuts run "Search Documents" -i - -o - | head
# Publish the front project's website, or a project by its folder
shortcuts run "Publish Website" -o -
echo ~/Notes | shortcuts run "Publish Website" -i - -o -
# Export a PDF next to the document (the Output field left empty)
shortcuts run "Export PDF" -i ~/Notes/post.md
# The list of broken links, in the front project
shortcuts run "Check Links" -o -
A small function makes this read like a command:
grasmere() { local name=$1; shift; printf '%s' "$*" | shortcuts run "$name" -i - -o -; }
grasmere "Append to Today's Entry" bread rose well today
grasmere "Open Document" "chapters/Low Water.md"
grasmere "Get Document Text" Revisions | wc -w
Two things to know:
- Some actions return a file. These are New Document, Append to Today’s Entry, Append to Document, the exports and Compile Folder. With
-o -you get the file’s contents, so a new document’s text, or a PDF’s bytes. That’s what you want for a document. For an export, either set the action’s Output field and leave-oout, or write the file with-o out.pdf. - A shortcut runs only while Grasmere is running or can be launched, and
shortcuts runopens it if need be. Publish Website and Compile Folder take as long as they take. The command waits, and you can carry on using the app meanwhile.
Running shortcuts from Grasmere
It works the other way round too. In Settings ▸ Automation, you can have Grasmere run one of your shortcuts whenever a document is saved, created or renamed, or a project is opened. See Saving, Safety and Git.