Beginner Guide to macOS Terminal for VoiceOver Users

By Marco Salsiccia. Updated March 4, 2026.

Welcome! This is a practical guide to using Terminal as a VoiceOver user. This is all information presented at the Intro to MacOS Terminal workshop hosted by the Andrew Heiskell Braille and Talking Books library of the NYPL.

What this Guide Covers

What Terminal is and command structure.
Creating, copying, moving, and deleting files and folders.
Finding files, finding text within files, and replacing text.
Useful tools like word and character count.
Installing the Homebrew package manager and going over usage basics.
Managing the .zprofile file and how PATH works.
Installing Python 3
Installing and using the TDSR Terminal screen reader, and setting up VoiceOver activities so they don't talk over each other.

What Terminal Is

Terminal is a text conversation with your Mac. You type a command, press Return, and get a response back. Once you get comfortable with a handful of commands, everyday file tasks can be faster and cleaner than moving about in Finder.

Terminal contains a plethora of tools just waiting to be installed and used. Code editors, video and photo editors, games, scripting libraries, and more. As you get better with Terminal, you can start thinking of how to put together scripts that automate the tedious or boring stuff you do on a day to day basis.

Where is Terminal?

Great question. You can find Terminal in the Utilities folder that's located inside the Applications folder.

In Finder, press Command+Shift+A to open the Applications folder, press U or navigate down to the Utilities folder, and Terminal will be inside.
Press Command+Space to open Spotlight, type Terminal, and hit Enter.

How Commands Work

Most commands follow this pattern:

command [flags] [arguments]

command: the tool you want to run, like ls, cp, or grep.

flags: small options that change behavior, like -l or -a.

arguments: the thing the command should work on, like a file name, folder, or search text.

ls Flag Examples

Same command, different output style:

ls

ls -l

ls -a

ls -la

ls: list names only.
ls -l: long details (permissions, owner, size, modified date).
ls -a: include hidden files.
ls -la: combine both flags.

Move Around Your Mac

Think of this as walking between folders before you do any file work.

Navigation Commands

pwd

ls

cd foldername

cd ..

cd ~

cd /

pwd: show where you are.
ls: show what is here.
cd: move between folders, or change directory.

Create, Copy, Move, and Delete

This is the everyday workflow for managing files and folders.

Create a Practice Folder

mkdir -p terminal-practice

cd terminal-practice

"mkdir" makes a directory, and the following command moves into that newly created directory.

Create Files and Folders

mkdir projects

touch notes.txt

The "touch" command will create an empty file. You can add almost any file type here when writing the extension. In this case it's a .txt text file, but you can use .html, .js, .css, .swift, .xml, .svg, and more.

Copy and Rename Files

cp notes.txt notes-backup.txt

mv notes.txt project-notes.txt

The "cp" command copies a file and lets you rename the copy, either in the same directory or in a new destination directory.

The "mv" or move command renames the original file and does not make a copy, and can be used to both rename and move the file, or to just move the file without renaming it to a new directory.

Delete Items Carefully

rm notes-backup.txt

rmdir empty-folder

rm permanently deletes files. Once you run this command, poof! They are completely gone. There is no standard undo/Trash step in this workflow, so it's best to be careful.

Safer Confirmation Flags

cp -i source.txt destination.txt

mv -i oldname.txt newname.txt

rm -i file.txt

The -i flag asks for confirmation before overwrite or delete actions. A much safer way to run these commands if you are unsure or want to catch mistakes before a totally destructive action.

Open Files, Folders, and Apps

These commands bridge Terminal and normal app windows.

Open from Terminal

open .

open notes.txt

open -a "TextEdit" notes.txt

open /Applications

The "open ." command opens your current working directory in Finder and will usually shift focus to Finder.

When opening files, you can use the "-e" flag to open it specifically in TextEdit rather than the default app for the file.

Read and Edit Text Files

Using Terminal, we can quickly read, edit, and save text in files.

Read Files

cat notes.txt

less notes.txt

"cat" is short for concatenate, and is good for reading short files in the Terminal.

"less" is meant for reading longer files. Less is more, get it? It contains a series of commands, such as Space Bar to go to the next page, "b" to go back a page, "q" to quit, plus searching commands. Type "less --help" to open a list of all the commands you can use.

Edit with nano

nano notes.txt

A very lightweight and simple text editor built right into Terminal. Great for beginners before moving on to heavier editors like vim or emacs. You'll be able to write directly in the Terminal, including using line breaks.

Save: Ctrl + O, then Return.
Exit: Ctrl + X.

Write Text with echo and Redirects

The echo command writes text output. With redirect operators, you can send that text directly into files.

echo "First line of notes" > notes.txt

echo "Another line of notes" >> notes.txt

cat notes.txt

A single > overwrites a file. If the file exists, old content is replaced.
A double >> appends to a file. New content is added at the end.
If the file does not exist, both operators create it.

This matters later for profile setup commands, where a single character changes whether you replace or add configuration lines.

Search for Files and Text

Use find to locate files and grep to locate text inside files.

Find Files by Name

The find command searches directories and returns matching paths.

find . -name "*.txt"

find . -iname "*.txt"

find . -type f -name "*.md"

find . -type d -name "projects"

find . -type f -name "*notes*"

find ~ -type f -name "*.pdf"

find . -maxdepth 2 -type f -name "*.txt"

-name: case-sensitive name matching.
-iname: case-insensitive name matching.
-type f: files only.
-type d: directories only.
-maxdepth 2: only search this folder and two levels below it.

How to read output: each line is a full or relative path to a match.

./terminal-practice/notes.txt

That means find located notes.txt inside the terminal-practice folder.

You may sometimes see permission denied messages when searching folders you do not own. That is normal and does not mean the command failed.

Find Text in Files

grep is a text-search tool. It scans files and returns lines that match the word or phrase you ask for.

grep -n "Terminal" notes.txt

grep -R -n "Terminal" .

-n: show line numbers.
-R: search recursively through subfolders.

Count Content with wc

wc is handy for quick counts when writing, checking logs, or reviewing file size at a glance. Perfect for grabbing quick word and character counts in any kind of text file.

wc Command Examples

wc notes.txt

wc -c notes.txt

wc -m notes.txt

wc -w notes.txt

wc -l notes.txt

wc: line, word, and byte counts.
wc -c: bytes.
wc -m: characters.
wc -w: words.
wc -l: lines.

Intermediate Example: Find and Replace Text

This is a practical way to replace repeated text while still keeping a backup.

Replace Text and Keep a Backup

sed is a stream editor. It can search for text patterns and replace them automatically.

sed -i.bak 's/old text/new text/g' notes.txt

cat notes.txt

cat notes.txt.bak

-i.bak edits the original file and writes a backup named notes.txt.bak.
s/old/new/g replaces every match on each line.

Install Homebrew

Homebrew is the easiest way to install Terminal tools on macOS. Think of it as a command-line app manager.

Run the Homebrew Installer

Copy the following command, paste the whole thing into Terminal, and hit Enter to begin the installation.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

What to Expect During Install

You will see a summary of what Homebrew will install and where.
You may be prompted for your macOS password. Typing is silent in Terminal.
At the end, the installer prints follow-up commands. Run those exactly as shown.

Shell Profile and PATH (Important)

This is one of the most useful Terminal ideas to learn early.

Your shell profile is a startup file that runs whenever a new shell opens. On macOS with zsh, that file is usually ~/.zprofile.

PATH is a list of folders your shell checks when you type a command name. If a tool's folder is in PATH, you can run it by name from anywhere.

Homebrew and TDSR both rely on this behavior, so understanding it now will save you time later.

Add Homebrew to PATH (Apple Silicon Example)

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile

eval "$(/opt/homebrew/bin/brew shellenv)"

The first command saves Homebrew PATH settings to your startup profile. The second applies it immediately to your current shell.

Verify Homebrew

brew --version

brew doctor

Official docs: brew.sh

Install Python on macOS

TDSR depends on Python 3. Install and verify it with Homebrew:

Install and Verify Python

brew install python

python3 --version

pip3 --version

Note: on many Macs, python may not point to Python 3. Use python3 unless instructions explicitly say otherwise.

Install and Run TDSR

While VoiceOver works fairly well in Terminal, TDSR gives a little more control over navigating the output. Rather than using VoiceOver, it supplies the output using system speech, all of which is configurable in the TDSR config settings.

TDSR allows you to use the left Option key to perform navigation and interaction commands.

Option+u: navigate up one line.
Option+i: read current line.
Option+o: Navigate down one line.
Option+j: navigate back one word.
Option+k: read current word.
Option+l: navigate to next word.
Option+m: Navigate to previous character.
Option+,: read current character.
Option+.: Read next character.
Option+c: Open config menu

TDSR is installed as a tool using the Terminal tool called "uv."

Install uv and TDSR

brew install uv

uv tool install git+https://github.com/tspivey/tdsr.git

The first command will install the "uv" tool. The second command utilizes the uv tool to grab the latest version of TDSR and install it on your system.

Open Terminal Settings, navigate to Profiles, open the Keyboard tab, and near the bottom of that window, toggle the "Use Option as meta key" in order to use the Option commands with TDSR before first running it.

Run and Check TDSR

~/.local/bin/tdsr

~/.local/bin/tdsr --help

If you get command not found, run TDSR with the full path above, then add ~/.local/bin to PATH in your profile.

Add TDSR Tools Folder to PATH

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile

source ~/.zprofile

Build a VoiceOver Activity for Terminal

If you want to prevent overlapping speech while using TDSR, create a VoiceOver Activity that mutes VoiceOver when Terminal is active:

Open Terminal.
Open VoiceOver Utility (VO + F8).
Go to Activities.
Add a new activity and name it something like Terminal.
Enable the Voices option for that activity.
Open Set Voices and enable Mute Speech.
Use Select Apps and Websites and choose Terminal.
Save and test by switching focus to Terminal.

Note: with this Activity active, you won't be able to hear VoiceOver in the Terminal settings window, so it's best to keep this Activity ready to go but don't implement it until you follow the next task of having TDSR start automatically.

Auto-Start TDSR for New Terminal Shells

You can launch TDSR automatically when a new Terminal window or tab opens.

In Terminal, open Settings.
Go to Profiles, then Shell.
Enable Run command.
Enter ~/.local/bin/tdsr as the command.
Enable Run inside shell so you still get a normal shell session.
Open a new tab to test.

If this feels too aggressive, keep manual startup and run TDSR only when needed.

Note: TDSR only works in the Terminal window and will only read out Terminal input and output. It will not work in the Terminal settings window, so if you need to change a setting, you'll have to disable the VoiceOver activity first so you can then navigate the window.

Useful Homebrew Commands

Everyday Homebrew Commands

brew search tdsr

brew list

brew list --cask

brew update

brew upgrade

Get Help for Any Command

You do not need to memorize every command. Terminal has built-in help tools you can use anytime.

Use the --help Flag

ls --help

grep --help

brew --help

The --help flag prints usage, available options, and examples for many commands.

Use Manual Pages (man)

man ls

man grep

man sed

Press Space for next page.
Press b for previous page.
Press / then type a word to search.
Press q to quit.

If a command has no manual page, try command --help instead.

Troubleshooting Quick Notes

command not found: check spelling, then check whether the tool is installed and in PATH.
permission denied: check file permissions or whether you are writing to a protected location.
Wrong folder mistakes: run pwd and ls before copy/move/delete commands.
Stop a running command with Ctrl + C.

Safety Checklist

Practice in a dedicated folder first.
Use pwd before copy/move/delete actions.
Use ls to confirm what is in the current folder.
Use -i flags when you want confirmation prompts.
Keep backup copies before bulk edits or find/replace operations.

What Comes Next

Now that you have basic knowledge of commands in Terminal, have installed a package manager and a dedicated screen reader, you can start effectively thinking about how to use this to take care of daily tasks.

All the commands on this page can be written up in shell scripts, or just text files that use the ".sh" file extension. Instead of inputting command after command line by line into Terminal, consider writing a script of all the commands you want to run in order, how you want the output to be handled, and that can all go into your very own script that can be run directly from the Terminal.

That will be another course entirely, but for now, come back to this page as many times as you need, use and share it as a quick start reference for anyone new to Terminal, and have fun scripting!