The halcyon command

halcyon opens a folder or a file from wherever you already are. A folder opens as a vault, a file opens in a window of its own, exactly as it would from Finder.

halcyon .            # this directory, as a vault
halcyon ~/notes      # a folder, as a vault
halcyon README.md    # one file, in a window of its own
halcyon              # bring Halcyon to the front

open is optional and exists so the command reads as a sentence, so halcyon open ~/notes does the same thing as the second line. The one place it matters: a directory actually named open has to be given as ./open.

halcyon --help prints the same summary.

Several paths at once work, and each is routed on its own:

halcyon ~/notes ~/work/spec.md

Installing it

Halcyon → Install Command Line Tool…

That puts the command in ~/.local/bin. It needs no admin rights, and app updates carry through without you reinstalling anything.

Note

~/.local/bin has to be on your PATH, and Halcyon can't tell whether it is: a GUI app inherits the system PATH, not your shell's. If halcyon comes back "command not found", that's what happened.

export PATH="$HOME/.local/bin:$PATH"

Put that in your ~/.zshrc and open a new terminal.

Moving, renaming or reinstalling Halcyon doesn't break the command.

To remove it: rm ~/.local/bin/halcyon.

What it can't do

It can't be your $EDITOR. The command returns the moment Halcyon accepts the file rather than waiting for you to close it, so there's nothing for git to wait on. There's no --wait, and a commit message opened this way would be committed empty.

It can't report an error from the app. A file Halcyon refuses says so in a dialog rather than in your terminal.

A path that doesn't exist is the one error it catches itself:

halcyon: no such file or directory: notes.md

Every path is checked before any of them opens, so a typo in the second of three doesn't open the other two.

Capture from a link

halcyon://capture does the same thing as Quick capture's hotkey, but from a link instead of a keypress - so Shortcuts, Raycast, or a shell script can drop a note into your vault without a hotkey ever being pressed.

open "halcyon://capture?text=Call the dentist back"

That's the whole interface: one link, one parameter. text is the note's entire body, sent exactly as given - nothing else in the link matters, so there's no folder or destination to pass. The capture lands wherever the hotkey's captures would: see Where it goes for how Halcyon picks the vault.

Turning it on

Off by default. Settings → Keybindings has an Allow halcyon://capture switch, unchecked on a fresh install. Until you turn it on, the link is refused rather than acted on - anything on your Mac that can run open can fire this link, which is a different threat than a hotkey only you can press.

What it won't do

It won't take a capture over 100,000 characters. Longer than that and Halcyon shows an alert and writes nothing, rather than saving part of what you sent.

It won't take an unlimited number of captures back to back. A burst of requests all at once, or a steady stream of them over a few minutes, gets cut off with an alert. Ordinary use, even scripted, never gets close to either limit - it exists for a runaway script, not for you.

It won't read folder, path, or anything else you put in the link. Only text does anything. A link built to point outside your vault has nothing in it that Halcyon reads that way.