Unix Man Pages (Non-Interactive)

Consult system manual pages for accurate command documentation. Prefer man pages over training data when precision matters.

CRITICAL: Never run bare man <command> - it opens an interactive pager that hangs.

How to Use Efficiently

Follow these rules to avoid flooding your context window:

1. Search first - If unsure of the command name, use mancat -k <keyword>
2. Target sections - Don't fetch the full man page immediately:
   • Read SYNOPSIS first to understand the structure
   • Read DESCRIPTION for a high-level overview
   • Fetch OPTIONS only when you need specific flags
3. Sanitization is automatic - The mancat tool strips formatting codes; raw control characters are handled

Usage Workflows

A. Discovery (Instead of Web Search)

When you don't know which command to use:

# CLAUDE_PLUGIN_ROOT is set automatically by Claude Code plugins
MANCAT="${CLAUDE_PLUGIN_ROOT}/skills/man/mancat.sh"
"$MANCAT" -k compress    # Returns: gzip, bzip2, tar, zip with descriptions
"$MANCAT" -k "file system"

B. Syntax Verification

When you know the command but need exact argument order:

"$MANCAT" -s SYNOPSIS tar
# Output: tar [-] A --catenate --concatenate | c --create | d --diff ...

C. Flag Investigation

When you need to understand a specific option:

"$MANCAT" -s OPTIONS tar
# Or for a specific flag:
"$MANCAT" tar | grep -A5 -- '-z'

Quick Start

# Use the mancat helper (recommended)
"${CLAUDE_PLUGIN_ROOT}/skills/man/mancat.sh" ls

# Or pipe through col -b
man ls | col -b

The mancat Helper

Use the included mancat.sh for convenient non-interactive access:

MANCAT="${CLAUDE_PLUGIN_ROOT}/skills/man/mancat.sh"

"$MANCAT" ls                 # Full man page, clean output
"$MANCAT" passwd 5           # Section 5 (file formats)
"$MANCAT" -s OPTIONS tar     # Extract just OPTIONS section
"$MANCAT" -k compress        # Search descriptions (apropos)

Manual Non-Interactive Patterns

Use these raw patterns when mancat.sh is unavailable or when piping to tools like grep/sed:

man <command> | col -b

The col -b filter strips backspace formatting codes, producing clean plain text.

Alternatives:

PAGER=cat man <command>    # Force no pager (may include escape codes)
man <command> | cat        # Simple but less clean on some systems

Efficient Lookups (Raw Patterns)

Full man pages waste context. Use targeted extraction with grep/sed:

Get Specific Option

man tar | col -b | grep -A5 -- '-z'
man curl | col -b | grep -A8 -- '--data'

Extract Section

# SYNOPSIS section
man ls | col -b | sed -n '/^SYNOPSIS/,/^[A-Z]/p' | head -20

# OPTIONS section (first 50 lines)
man curl | col -b | sed -n '/^OPTIONS/,/^[A-Z]/p' | head -50

# EXAMPLES section
man rsync | col -b | sed -n '/^EXAMPLES/,/^[A-Z]/p'

Limit Output Length

Always limit long pages:

man bash | col -b | head -100
man git-rebase | col -b | head -150

Quick Reference Commands

Search for Commands

man -k <keyword>              # Search names and descriptions
man -k compress | head -10    # Find compression tools
man -k "file system"          # Search phrase

One-Line Description

man -f tar
# tar (1) - manipulate tape archives

Check Man Page Exists

man -w grep >/dev/null 2>&1 && echo "has man page"

Get Man Page Path

man -w ls
# /usr/share/man/man1/ls.1

Man Page Sections

Specify section when a name exists in multiple:

man 1 printf | col -b   # Shell command
man 3 printf | col -b   # C library function
man 5 crontab | col -b  # File format
man 8 cron | col -b     # Daemon

Reading Man Output

SYNOPSIS - Command syntax. [] = optional, ... = repeatable.

OPTIONS - Flag descriptions with exact syntax.

EXAMPLES - Working command examples (not all pages have these).

SEE ALSO - Related commands worth checking.

When to Use Man Pages

• System commands (ls, find, tar) - Options vary by OS
• Config files (man 5 sudoers) - Syntax documentation
• Git subcommands (man git-rebase) - Full option reference
• Network tools (man curl, man ssh) - Protocol-specific flags