Index of every page on this site: llms.txt
All skills
flutter avatar

/unix-cli-best-practices

@ff6d472 official
by flutterflutter/agent-plugins3.2k stars
193
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/flutter/agent-plugins/unix-cli-best-practices

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈84 tokens for metadata: the name and description. ≈1.8k when used: this file.

Description uses 4.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈335 characters, or 4.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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:

# 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:

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.

# 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:

# 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:

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:
    ls -l | awk '{print $1, $3}'
  • Find and print duplicate lines in a file without sorting them first:
    awk '!seen[$0]++' filename.txt
  • Filter lines based on column values (for example, printing lines where the third column is greater than 100):
    awk '$3 > 100' data.txt
  • Find lines matching a pattern and print their line number (NR) along with the content:
    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.

# 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:

# 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:
    # 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:
    # 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:
    # Open the current directory in Finder
    open .
    
    # Open a local HTML file using a specific application
    open -a "Google Chrome" index.html

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts3mo3 checks · Risk SAFE
  • Gen Agent Trust Hub3mo

    This skill provides best practices and examples for using Unix and macOS command-line utilities. It contains educational content on how to use tools like grep, find, sed, and ripgrep efficiently and safely.

  • Socket3mo

    No alerts

  • Snyk3mo

    Risk: LOW · No issues

Signed by skilld at ff6d472. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 4 months ago

README badge

README badge for flutter/agent-plugins/unix-cli-best-practices