> ## Documentation Index
> Fetch the complete documentation index at: https://utter.to/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Shortcuts & Automation

> Control Utter from other apps with macOS completion commands, URL schemes, and iOS Shortcuts

Use automation to send Utter output to other apps, start or stop recording, and build hands-free workflows.

## iOS Shortcuts

Use iOS Shortcuts to start or stop recording without opening Utter.

### Fastest setup: use this ready-made shortcut

<span style={{display: "inline-flex", alignItems: "center", gap: "8px"}}>
  <img src="https://mintcdn.com/thirdtech/x5C3ziDkwU9vIhYg/images/shortcuts/apple-shortcuts-app-icon.png?fit=max&auto=format&n=x5C3ziDkwU9vIhYg&q=85&s=b102c1e5a7c7f3776ef3838e868d1b1f" alt="Apple Shortcuts app icon" style={{width: "24px"}} width="192" height="192" data-path="images/shortcuts/apple-shortcuts-app-icon.png" />

  <a href="https://www.icloud.com/shortcuts/dcff31152ac44dc189d4283b3797c3b3">Start/stop recording with one button and copy to clipboard</a>
</span>

This shortcut is the easiest way to use Utter hands-free:

* Press once to start recording.
* Press the same button or trigger again to stop recording.
* The transcript is copied to your clipboard automatically.
* You do not need to open Utter or the Shortcuts app.

Bind it to an iPhone trigger like **Action Button** or **Back Tap** (double tap on the back of your phone) for quick one-button dictation.

### Available Utter Shortcut Actions

| Shortcut Action  | Optional `Mode` Parameter | Behavior                                                                                        |
| ---------------- | ------------------------- | ----------------------------------------------------------------------------------------------- |
| Start Recording  | Yes                       | Starts recording. If `Mode` is not set, Utter uses the last used mode.                          |
| Stop Recording   | No                        | Stops recording and completes transcription.                                                    |
| Toggle Recording | Yes                       | Starts or stops recording with one action. If `Mode` is not set, Utter uses the last used mode. |

## macOS Completion Commands

On macOS, each mode can run a completion command after transcription finishes.

Use completion commands when you want Utter to send the final transcript to another app or script automatically. For example, you can append each finished dictation to your Obsidian daily note with the Obsidian CLI.

<Frame>
  <img src="https://mintcdn.com/thirdtech/JlHK0hFwT4s4tVIH/images/shortcuts/macos-completion-command.png?fit=max&auto=format&n=JlHK0hFwT4s4tVIH&q=85&s=5db936486ebe04b73a1e7c5338d84459" alt="Utter completion command field on macOS using the transcript output variable with an Obsidian CLI command" width="2350" height="1912" data-path="images/shortcuts/macos-completion-command.png" />
</Frame>

<Warning>
  Completion commands run shell commands on your Mac. Only use commands you trust.
</Warning>

### Add a Completion Command

<Steps>
  <Step title="Open Home">
    In Utter, go to **Home**.
  </Step>

  <Step title="Edit a Mode">
    Select the mode you want to automate.
  </Step>

  <Step title="Open Completion Command">
    In **Output**, open **Completion command** and click **Edit**.
  </Step>

  <Step title="Enter a Command">
    Add the shell command you want Utter to run after transcription.
  </Step>

  <Step title="Test and Save">
    Click **Test**, then click **Save**.
  </Step>
</Steps>

**What to expect:** After that mode finishes transcribing, Utter runs the command using `/bin/zsh -lc`.

### Available Variables

Use these variables in your command:

| Variable                            | Meaning                                                                      |
| ----------------------------------- | ---------------------------------------------------------------------------- |
| `$UTTER_TRANSCRIPT_OUTPUT`          | Final saved transcript output.                                               |
| `$UTTER_ORIGINAL_TRANSCRIPT_OUTPUT` | Original transcript text when the final output is enhanced; otherwise empty. |

### Example: Append to Obsidian

```bash theme={null}
obsidian daily --append-content=$UTTER_TRANSCRIPT_OUTPUT
```

## Dictation Controls

Control recording with these URLs:

| Action           | URL                        |
| ---------------- | -------------------------- |
| Start recording  | `utter://dictation/start`  |
| Stop recording   | `utter://dictation/stop`   |
| Pause recording  | `utter://dictation/pause`  |
| Cancel recording | `utter://dictation/cancel` |

## Mode Switching

Switch to a specific mode:

```
utter://mode/set/{mode-name}
```

Mode names are converted to lowercase kebab-case (for example, `Voice to Text` becomes `voice-to-text`):

| Mode Name      | URL                               |
| -------------- | --------------------------------- |
| Obsidian Notes | `utter://mode/set/obsidian-notes` |
| Email          | `utter://mode/set/email`          |
| Voice to Text  | `utter://mode/set/voice-to-text`  |

## Usage Examples

### Terminal

```bash theme={null}
open "utter://dictation/start"
```

### Shortcuts.app

<Steps>
  <Step title="Add Open URLs Action">
    Add an **Open URLs** action.
  </Step>

  <Step title="Enter Utter URL">
    Enter a Utter URL (for example, `utter://dictation/start`).
  </Step>

  <Step title="Run Shortcut">
    Run the shortcut to trigger Utter.
  </Step>
</Steps>

**What to expect:** Utter runs the matching action immediately when the shortcut is executed.

**If that did not work:** Confirm Utter is installed and currently running before triggering the URL.

### Raycast / Alfred

Create a script or workflow that opens the URL:

```bash theme={null}
open "utter://mode/set/email"
open "utter://dictation/start"
```

### Keyboard Maestro

Use the **Open URL** action with any Utter deep link to trigger it from a macro.