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:

  1. Install Snackbar from the Chrome Web Store
  2. Open a workspace and click Add Link → App
  3. Select crystl from the app dropdown
  4. Choose Local (enter a project path) or SSH (enter host and remote path)
  5. 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@host and cd /path, both shell-escaped. The -- means the host can never be read as an ssh option. 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.