# Deep Links Deep links let other apps and scripts run actions in Fluent. Anything that can open a URL can run an action, send a prompt, and even pass Fluent a file, e.g. Shortcuts, Terminal, AppleScript, Alfred, Stream Deck, or a link saved in your notes. Every deep link starts with `fluent://v1/`. ```text fluent://v1/actions/run?id=fixGrammar&text=Their%20going%20to%20the%20store ``` If Fluent is not running, macOS opens it first. ----- ## Run an Action `fluent://v1/actions/run` runs an action or a prompt. | Parameter | What it does | | --- | --- | | `id` | The action to run | | `text` | The input text, as if you had selected it | | `prompt` | Without `id`: the prompt to run. With `id`: an extra instruction for this run only | | `file` | A file to attach. Repeat it to attach several files | | `background` | `true` runs the action without opening the Smart Panel | A link needs `id`, `prompt`, or both. Everything else is optional. Fluent opens the Smart Panel in the middle of the screen, adds the text and files, and runs the action there, just as if you had picked it from Favorites. You can then review the result, ask a follow-up, or copy it. Examples: ```text fluent://v1/actions/run?id=summarizeText&file=~/Documents/report.pdf fluent://v1/actions/run?prompt=Plan%20my%20day fluent://v1/actions/run?id=translatorGeneric&prompt=Translate%20into%20Spanish&text=See%20you%20tomorrow ``` With both `id` and `prompt`, the action keeps its own prompt, model, and settings, and your instruction is added to the end. The action itself doesn't change. ----- ## Find an Action ID Open the **Actions** window, right-click an action, and choose **Copy ID**. Built-in actions have readable IDs, such as `fixGrammar`, `summarizeText`, or `translatorGeneric`. Actions you create get a long unique ID. IDs are case-sensitive. An action keeps its ID when you rename or edit it. A duplicate gets its own ID. ----- ## Text and Files Use `text` for short input. For anything longer than a sentence or two, save it to a file and pass `file` instead. Long URLs get unwieldy fast, and every special character in them has to be encoded. `file` accepts: - A full path: `/Users/me/Documents/notes.md` - A path in your home folder: `~/Documents/notes.md` - A file URL: `file:///Users/me/Documents/notes.md` When a link has exactly one file and no `text`, Fluent reads the file and uses its contents as the input text, the same as if you had selected it. This works for plain text, Markdown, PDF, Word, RTF, HTML, and Excel files. Images stay images, so a vision model can see them. Links with several files attach them all, the same way as dropping them on the Smart Panel. A file that doesn't exist is skipped. ----- ## Encoding Deep links are URLs, so text and paths in them must be URL-encoded. Common cases: - Space → `%20` - `&` → `%26` - `?` → `%3F` - `#` → `%23` - New line → `%0A` Use `%20` for spaces, not `+`. Fluent keeps `+` as a plus sign. In Shortcuts, use the **URL Encode** action. In scripts, use your language's URL encoding function. ----- ## Run in the Background Add `background=true` to run without opening the Smart Panel. Fluent runs the action with its own model and settings, saves the result to **History**, and notifies you when it finishes, the same way scheduled actions run. Click the notification to open the result. Background runs work best for actions that don't need your review, such as summaries, digests, extracting action items, or saving tasks to Reminders. A few things to keep in mind: - An action already running in the background ignores new links for it until it finishes. To run several at once, use `prompt` without `id` - Actions don't ask you questions in the background - To turn off the notification, change it in the action's **Schedule** settings ----- ## Use Cases **Summarize Any File from Finder** Build a Quick Action once, then right-click any document in Finder and choose **Quick Actions** → **Summarize with Fluent**. In the **Shortcuts** app, create a shortcut named "Summarize with Fluent": 1. In the shortcut's details, turn on **Use as Quick Action** and choose **Finder** 2. Add **Get Details of Files** and choose **File Path** 3. Add **URL Encode** 4. Add **Text** with `fluent://v1/actions/run?id=summarizeText&file=` followed by the **URL Encoded Text** variable 5. Add **Open URLs** The Smart Panel opens with the summary. Swap `summarizeText` for any action ID to make more Quick Actions, for example one that translates a document or pulls action items out of a transcript. **One-Click Prompts** For questions you ask every day, save the prompt as a link and open it with one click. ```text fluent://v1/actions/run?prompt=What%20is%20on%20my%20calendar%20today%20and%20what%20is%20overdue%20in%20Reminders%3F ``` Put the link anywhere that opens URLs: - A Shortcuts shortcut with **Open URLs**, pinned to the menu bar or given a keyboard shortcut - A Stream Deck button - A note or a calendar event Prompts that use integrations need those integrations enabled in **Settings → Integrations**, the same as when you type them. **Hands-Free Summaries of New Files** When new files keep landing in one folder, such as meeting transcripts, exports, or reports, Fluent can summarize each one in the background as it arrives. In **Automator**, create a new **Folder Action** and choose the folder. Add **Run Shell Script**, set **Pass input** to **as arguments**, and paste: ```bash for f in "$@"; do open "fluent://v1/actions/run?prompt=Summarize%20this%20file.%20End%20with%20the%20decisions%20and%20action%20items.&file=${f// /%20}&background=true" done ``` Save it. Each new file is summarized, the result goes to **History**, and a notification tells you when it's ready. This uses `prompt` without `id` on purpose. Each prompt link runs on its own, so every file gets its own summary even when several arrive at once. The same `open` command works from Terminal, shell scripts, and tools like Hazel. In AppleScript, use `open location "fluent://v1/..."`. ----- ## Troubleshooting **The Smart Panel opens, but nothing runs.** The ID doesn't match any action. Copy it again from the **Actions** window. IDs are case-sensitive, and a deleted action's ID stops working. **Text is cut off.** A character wasn't encoded. An unencoded `&` ends the text early, and `#` drops the rest of the link. Encode the text, or pass it as a file. **A file is missing.** Check that the path exists and is a full path or starts with `~/`. Relative paths such as `Documents/notes.md` are ignored. Encode spaces in paths as `%20`. **A background link does nothing.** The same action may still be running from an earlier link. Wait for its notification, or check **History**. Also check the ID: in the background, an unknown ID does nothing.