---
name: unix-cli-best-practices
description: Safe, portable, and efficient command-line patterns for macOS/BSD Unix tools (grep, find, sed, awk, xargs, mdfind, pbcopy, open) and modern alternatives (ripgrep, fd). Covers common shell scripting and one-liner use cases including fast searching, text processing, codebase navigation, and parallel execution.
title: unix-cli-best-practices
canonical_url: https://skilld.dev/gh/flutter/agent-plugins/unix-cli-best-practices
last_updated: 2026-09-29T12:24:03.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install flutter/agent-plugins/unix-cli-best-practices`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/unix-cli-best-practices`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/flutter/agent-plugins/unix-cli-best-practices) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/unix-cli-best-practices`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/unix-cli-best-practices --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/unix-cli-best-practices --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Unix CLI best practices

This guide provides efficient, safe, and portable techniques for manipulating text and finding files from the command line on macOS. By default, macOS uses BSD-derived UNIX utilities (`grep`, `find`, `sed`, `awk`) which have subtle differences from their GNU/Linux counterparts.

When possible, use high-performance replacements (`ripgrep` and `fd`) which respect `.gitignore` rules by default and offer more ergonomic interfaces.

## Modern high-performance alternatives

Use these tools instead of standard BSD utilities for local codebase operations.

### ripgrep (`rg`)

Use `ripgrep` (`rg`) as the preferred tool for searching text. It is faster than standard `grep` and respects `.gitignore` rules by default.

Common use cases:
* Run `rg 'search_term'` to recursively search the current directory.
* Run `rg -S 'term'` to search case-insensitively unless the query contains uppercase letters. Use `rg -i 'term'` for strict case-insensitivity.
* Run `rg -g '*.ts' -g '!*.spec.ts' 'term'` to search `.ts` files while excluding `.spec.ts` files.
* Run `rg -v 'ignore_me'` to print lines that do not match the pattern.
* Run `rg -l 'term'` to list only the names of matching files. Combine with `rg -0` for null-terminated output suitable for `xargs`.
* Run `rg -F 'foo()'` to treat the search pattern as a fixed string rather than a regular expression.
* Run `rg -w 'const'` to match whole words only.
* Run `rg -C 2 'term'` to show two lines of surrounding context. Use `rg -B 2` for preceding context or `rg -A 2` for succeeding context.

Refer to `rg --help` for the complete options list.

### fd

Use `fd` as the preferred tool for traversing the filesystem and finding files. It is faster than standard `find` and respects `.gitignore` rules by default.

Common use cases:
* Run `fd 'pattern'` to find files matching the regex pattern anywhere in their path.
* Run `fd -e py -e txt` to filter results by file extensions.
* Run `fd -t d 'docs'` to find directories. Use `fd -t f` for files and `fd -t l` for symbolic links.
* Run `fd -H` to include hidden files, or `fd -I` to include ignored files (such as `node_modules`). Combine as `fd -HI` to search all files.
* Run `fd -p 'src/assets'` to match the pattern against the full path instead of just the filename.
* Run `fd -e log -x rm` to execute a command on each matching file individually. Use `-X` (e.g., `fd -e log -X rm`) to run the command once with all matching files as arguments.
* Run `fd -a 'pattern'` to return absolute paths instead of relative paths.

Refer to `fd --help` for the complete options list.

## Built-in tools for macOS and BSD

Use these built-in utilities only when `rg` and `fd` are unavailable. Apply precise filters to prevent performance degradation.

### Efficient searching with grep

Do not use `grep | grep -v 'unwanted_dir'` to exclude directories. This approach reads all files before filtering them. Use native exclusion arguments instead to exclude directories at the filesystem level:

```bash
# Slow: reads binary and ignored files
grep -R "pattern" . | grep -v "node_modules"

# Fast: skips the directory completely at the filesystem level
grep -R --exclude-dir=node_modules --exclude-dir=.git "pattern" .
```

Common `grep` flags:
* `-r` or `-R` to search recursively. `-R` follows symbolic links, while `-r` does not.
* `-I` to ignore binary files for faster execution and clean output.
* `--exclude="*.min.js"` to ignore files matching a specific glob.
* `--include="*.dart"` to search only files matching a specific glob.
* `-l` to print only the names of files containing matches.
* `-Z` to print a null character after each filename, which is useful when piping to `xargs -0`.

Example of safely deleting files containing a specific string:
```bash
grep -rlZ -I --exclude-dir=node_modules "DEPRECATED_API" . | xargs -0 rm
```

### High-performance traversal with find

Prevent `find` from traversing irrelevant directory trees by using the `-prune` option.

```bash
# Slow: traverses node_modules entirely, then filters output
find . -name "*.ts" | grep -v "node_modules"

# Fast: skips node_modules entirely
find . -name "node_modules" -prune -o -name "*.ts" -print
```

The expression `-name "node_modules" -prune` stops traversal when encountering a `node_modules` directory. The `-o` (OR) operator specifies that for any other directory or file ending in `.ts`, the path is printed.

### macOS portability with sed

macOS uses BSD `sed`, which differs from GNU `sed` in its handling of in-place editing.

Use the `-i` option with an explicit backup extension. To edit in-place without creating a backup, provide an empty string:

```bash
# Edit in-place without creating a backup
sed -i '' 's/oldName/newName/g' filename.txt

# Edit in-place and create a backup named filename.txt.bak
sed -i '.bak' 's/oldName/newName/g' filename.txt
```

Use the `-E` option to enable extended regular expressions, avoiding the need to escape parentheses and plus signs:
```bash
sed -E 's/(foo|bar)+/baz/g' file.txt
```

### Codebase analysis with awk

Use `awk` for line-by-line data extraction and text processing.

Common use cases:
* Print specific columns from space-separated input:
  ```bash
  ls -l | awk '{print $1, $3}'
  ```
* Find and print duplicate lines in a file without sorting them first:
  ```bash
  awk '!seen[$0]++' filename.txt
  ```
* Filter lines based on column values (for example, printing lines where the third column is greater than 100):
  ```bash
  awk '$3 > 100' data.txt
  ```
* Find lines matching a pattern and print their line number (`NR`) along with the content:
  ```bash
  awk '/Error/ {print NR, $0}' server.log
  ```

### Safe pipelines and parallelism with xargs

Use `xargs` to build and execute commands from standard input. Always use the `-0` option (null-terminated) when processing file paths to handle filenames containing spaces or special characters safely.

```bash
# Unsafe: will fail or perform unintended actions if filenames contain spaces
find . -name "*.log" | xargs rm

# Safe: handles spaces and special characters correctly
find . -name "*.log" -print0 | xargs -0 rm
```

Use the `-P` option to run tasks in parallel:
```bash
# Run up to 4 curl processes in parallel
cat urls.txt | xargs -n 1 -P 4 curl -O
```

### macOS-specific CLI tools

Use macOS-specific utilities to interact with operating system features:

* Use `mdfind` to query the macOS Spotlight index for fast, global file and content searches without scanning the disk:
  ```bash
  # Search by filename
  mdfind -name "project_spec"

  # Search by text content within files
  mdfind "kMDItemTextContent == 'TODO: Refactor'"
  ```
* Use `pbcopy` and `pbpaste` to interact with the system clipboard:
  ```bash
  # Copy file content to the clipboard
  cat ssh_key.pub | pbcopy

  # Paste clipboard content to a file
  pbpaste > new_file.txt
  ```
* Use `open` to open files, directories, or URLs with their default applications:
  ```bash
  # Open the current directory in Finder
  open .

  # Open a local HTML file using a specific application
  open -a "Google Chrome" index.html
  ```
