Creating Pipelines

This guide walks you through creating pipelines to automate tasks with your voice.

---

Creating Your First Pipeline

1. Open Pipeline Settings

1. Open Freeway Preferences
2. Go to the Pipelines tab
3. Click Add First Pipeline (or Add Pipeline if you have existing ones)

2. Configure the Pipeline

Fill in the required fields:

• Name: A descriptive name (e.g., “Uppercase Converter”)
• Trigger Pattern: The text pattern to match (e.g., “make uppercase”)
• Match Type: How to match the pattern (e.g., “Starts with”)
• Shell Command: The command to run

3. Test with “Try It”

Click the Try it button to test your pipeline:

1. Enter sample input text
2. Click Run
3. View the output (or error)

4. Save

Click Save to activate your pipeline.

---

Pipeline Fields

Name

A descriptive name for your pipeline. This appears in the pipeline list and in status messages.

Tip

Use clear, action-oriented names like “Convert to Uppercase” or “Open in Browser”.

Trigger Pattern

The text pattern that activates this pipeline. Combined with the match type, this determines when your pipeline runs.

Tips:

• Keep patterns short and distinct
• Avoid patterns that overlap with normal speech
• Test patterns to ensure they don’t trigger accidentally

Match Type

Choose how the pattern is matched:

Match Type	Best For
Starts with	Commands like “open…”, “search for…”
Ends with	Suffixes like “…please”, “…now”
Exact match	Specific phrases like “toggle dark mode”
Contains	Keywords that can appear anywhere
Regex	Complex patterns with captures

Shell Command

The shell command to execute. This can be:

• A simple command: date
• A pipeline: tr '[:lower:]' '[:upper:]'
• A script: python3 /path/to/script.py
• Multiple commands: echo "hello" && say "hello"

---

Writing Shell Commands

Receiving Input

Your command receives the transcribed text via:

# stdin - pipe-friendly
cat | your-command

# Environment variable - use in scripts
echo "$FREEWAY_TEXT"

Producing Output

Output	Result
Non-empty stdout	Replaces the transcribed text (pasted)
Empty stdout	Skip paste (nothing is pasted)
stderr	Shown as error message
Non-zero exit code	Treated as error

Examples

Transform text (output replaces input):

# Uppercase
tr '[:lower:]' '[:upper:]'

# Lowercase
tr '[:upper:]' '[:lower:]'

# Reverse lines
tac

# Sort lines
sort

Action only (empty output skips paste):

# Copy to clipboard
pbcopy

# Open URL
open "https://google.com"

# Play sound
afplay /System/Library/Sounds/Glass.aiff

# Show notification
osascript -e 'display notification "Done!" with title "Freeway"'

Both action and output:

# Copy to clipboard AND paste
tee >(pbcopy)

# Log AND output
tee -a /tmp/freeway.log

---

Match Type Details

Starts With

Matches if the transcribed text begins with the pattern.

Pattern: open Matches: “open terminal”, “open finder”, “open the door” Doesn’t match: “please open”, “reopen”

# Extract what to open
open_what=$(echo "$FREEWAY_TEXT" | sed 's/^open //')
open "$open_what"

Ends With

Matches if the transcribed text ends with the pattern.

Pattern: please Matches: “help me please”, “do it please” Doesn’t match: “please help me”

Exact Match

Matches if the transcribed text exactly equals the pattern (case-insensitive).

Pattern: toggle dark mode Matches: “toggle dark mode”, “Toggle Dark Mode” Doesn’t match: “toggle the dark mode”, “dark mode toggle”

Contains

Matches if the pattern appears anywhere in the text.

Pattern: weather Matches: “what’s the weather”, “weather forecast”, “check weather please”

Caution

Be careful with short patterns — they may match unintentionally.

Regex

Matches using a regular expression (ICU syntax). Matching is case-insensitive. Text is normalized before matching: punctuation removed, whitespace trimmed.

Common patterns:

Pattern	Matches
^hey freeway	Text starting with “hey freeway”
please$	Text ending with “please”
^(open|start) chat	”open chat” or “start chat” at the beginning
^(open|launch|start)	Text starting with “open”, “launch”, or “start”
send (email|message) to	”send email to…” or “send message to…”
remind me in \d+ minutes	”remind me in 5 minutes”, “remind me in 30 minutes”
^translate .+ to (spanish|french|german)$	”translate hello to spanish”
^(what|who|where|when|why|how)\b	Questions starting with interrogative words
^search (for|on )?	”search cats”, “search for cats”, “search on google”

Example — search command:

Pattern: ^search for (.+)$ Matches: “search for cats” → captures “cats”

# Using regex in shell
if [[ "$FREEWAY_TEXT" =~ ^search\ for\ (.+)$ ]]; then
    query="${BASH_REMATCH[1]}"
    open "https://google.com/search?q=$(echo "$query" | sed 's/ /+/g')"
fi

Example — multi-word trigger:

Pattern: ^(hey|ok|hi) freeway Matches: “hey freeway do something”, “ok freeway search”

# Strip trigger phrase and process the rest
command=$(echo "$FREEWAY_TEXT" | sed -E 's/^(hey|ok|hi) freeway[,]? *//')
echo "Command: $command"

Example — optional words:

Pattern: ^open (the )? Matches: “open terminal”, “open the finder”

# Extract app name, handling optional "the"
app=$(echo "$FREEWAY_TEXT" | sed -E 's/^open (the )?//')
open -a "$app"

---

Using Scripts

For complex logic, call external scripts:

Python Script

python3 /path/to/script.py

#!/usr/bin/env python3
import sys

text = sys.stdin.read()
# Process text...
print(text.upper())

Bash Script

/path/to/script.sh

#!/bin/bash
read text
# Process text...
echo "${text^^}"  # Uppercase in bash 4+

AppleScript

osascript /path/to/script.scpt

Or inline:

osascript -e 'tell application "Finder" to make new folder'

---

Timeout

Pipelines have a 30 second timeout. If your command takes longer, it will be terminated.

For long-running tasks:

• Run them in the background: your-command &
• Use disown or nohup
• Start a detached process

# Run in background, no output (skip paste)
nohup long-running-task &>/dev/null &

---

Debugging

Enable Logging

Add logging to your shell command:

echo "Input: $FREEWAY_TEXT" >> /tmp/pipeline-debug.log
your-command | tee -a /tmp/pipeline-debug.log

Check Exit Codes

Test commands in Terminal first:

echo "test input" | your-command
echo $?  # Should be 0 for success

View Freeway Logs

Errors appear in:

• Status message in Freeway visualizer
• Freeway debug console (menu bar → Debug)

---

Best Practices

1. Test thoroughly — Use “Try it” before relying on a pipeline
2. Keep patterns distinct — Avoid overlapping triggers
3. Handle errors — Check for empty input, missing dependencies
4. Use absolute paths — Don’t rely on PATH for scripts
5. Avoid slow commands — Keep execution under a few seconds
6. Order matters — Put specific patterns before general ones