TL;DR
Stash is a command-line tool that synchronizes Markdown files with Apple Notes in both directions, using front-matter to track note identity. It relies on AppleScript for Notes access and uses Pandoc to convert between Markdown and HTML; installation is available via a Homebrew tap.
What happened
A developer published Stash, a small CLI designed to move Markdown content to and from Apple Notes. Users can push a local .md file to create or update a corresponding Apple Note; the tool inserts or updates front-matter with a unique apple_notes_id to keep the association. Pull operations reverse the flow, replacing the local Markdown body with the current content from the linked Apple Note while preserving the front-matter. Stash is implemented as a three-layer system: AppleScript handles direct interaction with Apple Notes, shell scripts orchestrate sync logic and front-matter handling, and Pandoc performs Markdown↔HTML conversion. The project includes a Homebrew formula for installation, a test suite (unit and integration), and a release workflow driven by a Makefile. A public backlog lists planned enhancements such as diffs and attachments support.
Why it matters
- Provides a lightweight bridge between a Markdown-first writing workflow and Apple Notes without a GUI.
- Bidirectional sync lets users keep source files in Git or local folders while reading and editing notes on Apple devices.
- Runs from the shell with no required configuration files, aiming for simplicity and reproducibility.
- Uses platform-native automation (AppleScript) and Pandoc conversion to preserve formatting across systems.
Key facts
- Primary commands: stash push <file.md> to send Markdown to Apple Notes, stash pull <file.md> to retrieve note content back.
- The tool adds or updates YAML front-matter in Markdown files with apple_notes_id to track linked notes.
- Requires macOS with Apple Notes available, plus Pandoc for format conversion and pcregrep for front-matter parsing.
- Implementation layers: AppleScript for Notes access, shell scripts for sync logic, Pandoc for conversion, and Bashly for CLI scaffolding.
- Distributed via a Homebrew tap; installation instructions are provided in the repository.
- Repository includes a Makefile for building, testing, and creating releases; releases update the Homebrew formula as part of the workflow.
- The test suite includes unit tests that can run without Apple Notes and integration/e2e tests that require Notes access.
- A public backlog and CONTRIBUTING notes list planned features and invite contributions, including nicer diffing and attachment handling.
What to watch next
- Planned "diff changes" feature in the backlog (aimed at showing or merging differences between local and remote) — currently listed as a future item.
- Attachment support is on the project's nice-to-have list and may appear in later updates.
- Updates to the Homebrew formula and release automation (make release) which publish new versions and modify the formula.
Quick glossary
- Front-matter: A YAML block at the top of a text file used to store metadata such as identifiers or configuration used by tools.
- AppleScript: A macOS scripting language for automating interactions with Apple applications and system services.
- Pandoc: A document conversion tool that can translate between formats such as Markdown and HTML.
- CLI (Command-Line Interface): A text-based interface for interacting with software using commands typed into a terminal or shell.
- Homebrew: A package manager for macOS that simplifies installing and managing command-line software.
Reader FAQ
Which platforms does Stash support?
Requires macOS with Apple Notes; other platforms are not supported in the repository instructions.
Does Stash sync in both directions?
Yes. The tool supports pushing Markdown to Apple Notes and pulling Note content back into Markdown.
How do I install Stash?
The repository shows installation via a Homebrew tap and formula: brew tap shakedlokits/stash <repo-url> then brew install shakedlokits/stash/stash.
Is there a graphical interface or editor included?
not confirmed in the source
▄█████ ██████ ▄████▄ ▄█████ ██ ██ ▀▀▀▄▄▄ ██ ██▄▄██ ▀▀▀▄▄▄ ██████ █████▀ ██ ██ ██ █████▀ ██ ██ Bidirectionally sync Markdown files with Apple Notes! Getting Started Installation brew tap…
Sources
- Show HN: Stash – Sync Markdown Files with Apple Notes via CLI
- Ask HN: How do you synchronise your notes?
- The best note taking apps for Mac – markdown, open format …
- Can I interact with Apple Notes app from the command line?
Related posts
- CES 2026 roundup — weird, wild and wonderful tech reveals from Las Vegas
- Kentucky rolls out mobile ID app; Apple Wallet support due this summer
- Asus debuts 16‑inch Zenbook A16 at CES 2026 — a notably light laptop