# URL Scheme

> Open projects and SSH sessions in Crystl from other apps, scripts, Raycast, or web links using crystl:// URLs.

Crystl registers the `crystl://` URL scheme so other apps, scripts, and web links can open projects directly — no GUI required.

## Open a Local Project

```
crystl:///absolute/path/to/project
```

**Examples:**

```bash
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:**

```bash
open "crystl://ssh/root@myserver.com/var/www"
open "crystl://ssh/deploy@staging.example.com/opt/app"
```

Crystl creates a new gem, connects to the host via `ssh user@host`, waits for the connection, then `cd`s to the remote path. The gem is titled with the hostname.

The remote path is optional — omit it to land in the default SSH home directory:

```bash
open "crystl://ssh/root@myserver.com"
```

## Snackbar

[Snackbar](https://chromewebstore.google.com/detail/snackbar/mgcdhigmdnfhjcbmlkppaeljcnpbmjed) is a Chrome sidebar extension for organizing projects — workspaces, saved links, notes, and tasks, all in a sliding panel that stays accessible without leaving your current tab.

The `crystl://` URL scheme was originally added for Snackbar: save a `crystl:///path/to/project` link in a workspace and clicking it opens that project in Crystl directly from the browser. For remote work, save a `crystl://ssh/user@host/path` link to jump straight into a server session.

Snackbar has built-in Crystl support — no URL construction needed. When adding a link, choose **App → Crystl**, then pick **Local** or **SSH** and fill in the path or host.

**Setup:**

1. Install [Snackbar](https://chromewebstore.google.com/detail/snackbar/mgcdhigmdnfhjcbmlkppaeljcnpbmjed) 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 — macOS will ask once to confirm opening Crystl, then open the gem directly

## 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. 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](/docs/cli) — control Crystl programmatically over HTTP
- [Remote SSH Sessions](/docs/remote-ssh) — SSH tunneling and remote session management

---
Source: https://crystl.dev/docs/url-scheme/