URL Scheme
Updated November 15, 2026
crystl registers the crystl:// URL scheme so other apps, scripts, and web links can open projects directly, no GUI required.
Snackbar (the easy way)
Snackbar is a free Chrome side panel for organizing projects: workspaces, saved links, notes, and tasks, all in a sliding panel that stays accessible without leaving your current tab. It has built-in crystl support, so you never construct a URL by hand.
Save a project as a link and one click opens it as a gem in crystl. Save a server and one click drops you into an SSH session, already cd’d to the right path. It is the same multitasking crystl gives you, now spanning your browser and your terminal.
Setup:
- Install Snackbar from the Chrome Web Store
- Open a workspace and click Add Link → App
- Select crystl from the app dropdown
- Choose Local (enter a project path) or SSH (enter host and remote path)
- Click the link, and macOS will ask once to confirm opening crystl, then open the gem directly
Prefer to wire deep links into your own tools instead? The raw crystl:// URLs are below.
Open a local project
crystl:///absolute/path/to/project
Examples:
open "crystl:///Users/chris/Projects/myapp"
open "crystl:///Users/chris/Nextcloud/crystl"
If the path exists and is a directory, crystl opens it as a new gem and brings the window to the front. If crystl isn’t running, it launches first.
Open an SSH session
crystl://ssh/user@host/remote/path
Examples:
open "crystl://ssh/[email protected]/var/www"
open "crystl://ssh/[email protected]/opt/app"
crystl creates a new gem and opens a shard with ssh to the host. If the host asks for a password or a 2FA code, type it in that shard. crystl waits for the login however long it takes, then cds to the remote path. The gem is titled with the hostname.
The gem remembers its host and its folder. Its sidebar row shows an ssh mark, every new shard in it connects to the host and lands in that folder, and after a restart its shards reconnect.
The URL takes user@host, host, or a name from your ~/.ssh/config. It takes no ssh flags. For a port, a key file or a jump host, add a Host entry to ~/.ssh/config and use its name.
The remote path is optional. Omit it to land in the default SSH home directory:
open "crystl://ssh/[email protected]"
The same thing from the app
You don’t need a URL to open a remote gem. The folder button at the bottom of the gem sidebar has a this mac / remote switch that opens the same kind of gem, and the New Gem panel has one that also creates the folder on the host. The URL only opens what is already there. See remote SSH.
Other use cases
- Raycast / Alfred: bookmark frequently used projects or servers as URL actions
- Scripts and CI: open a project from a shell script without knowing if crystl is already running
- Browser bookmarks: link to a project from internal docs or a dashboard
- Other apps: deep-link into crystl from a project manager, IDE, or deployment tool
Security
Both URL actions are safe by design:
- Local open: crystl checks the path exists and is a directory before doing anything. Non-existent paths are silently ignored.
- SSH open: the only commands sent to the terminal are
ssh -- user@hostandcd /path, both shell-escaped. The--means the host can never be read as ansshoption. A crafted URL cannot inject arbitrary commands.
macOS shows a confirmation prompt the first time a foreign app fires a crystl:// URL, so users see what’s being opened before it happens.
Related
- CLI & scriptability API: control crystl programmatically over HTTP
- remote SSH sessions: SSH tunneling and remote session management