.TH PATHMASTER 1 "April 2024" "Version 1.0" "User Commands"
.SH NAME
pathmaster \- A powerful tool for managing your system's PATH environment variable
.SH SYNOPSIS
.B pathmaster
.IR COMMAND
[OPTIONS] [ARGUMENTS]
.SH DESCRIPTION
.B pathmaster
is a comprehensive tool for managing your system's PATH environment variable. It provides functionality for adding and removing directories, validating PATH entries, managing backups, and maintaining PATH integrity.
.SH COMMANDS
.TP
.BR add ", " \-a " <directory>..."
Add one or more directories to your PATH. Each directory is validated before addition.
Multiple directories can be specified at once.
.TP
.BR delete ", " \-d " <directory>..."
Remove one or more directories from your PATH.
Alias: remove
.TP
.BR list ", " \-l
List all current entries in your PATH, displaying them in a clear, readable format.
.TP
.BR history ", " \-y
Show the backup history of your PATH, displaying available backups with timestamps.
.TP
.BR restore " [" \-\-timestamp " <timestamp>]"
Restore your PATH from a previous backup. If no timestamp is provided, restores from the most recent backup.
.TP
.BR flush ", " \-f
Remove all non-existing directories from your PATH automatically.
.TP
.BR check ", " \-c
Validate current PATH entries, identifying invalid or missing directories.
.SH OPTIONS
.TP
.BR \-\-help
Display help information about pathmaster and its commands.
.TP
.BR \-\-version
Display version information.
.SH EXAMPLES
.SS Adding Directories
Add a single directory:
.PP
.nf
.RS
pathmaster add ~/bin
.RE
.fi
Add multiple directories:
.PP
.nf
.RS
pathmaster add ~/bin ~/scripts /usr/local/bin
.RE
.fi
.SS Removing Directories
Remove a directory:
.PP
.nf
.RS
pathmaster delete ~/old/bin
.RE
.fi
Remove multiple directories:
.PP
.nf
.RS
pathmaster delete ~/old/bin ~/deprecated/scripts
.RE
.fi
.SS Listing PATH Entries
View current PATH:
.PP
.nf
.RS
pathmaster list
.RE
.fi
.SS Managing Backups
View backup history:
.PP
.nf
.RS
pathmaster history
.RE
.fi
Restore from specific backup:
.PP
.nf
.RS
pathmaster restore --timestamp 20240421120000
.RE
.fi
Restore from most recent backup:
.PP
.nf
.RS
pathmaster restore
.RE
.fi
.SS Maintaining PATH
Remove invalid paths:
.PP
.nf
.RS
pathmaster flush
.RE
.fi
Check for invalid directories:
.PP
.nf
.RS
pathmaster check
.RE
.fi
.SH FILES
.TP
.I ~/.pathmaster_backups/
Directory where PATH backups are stored as JSON files.
.TP
.I ~/.bashrc
Bash shell configuration file that may be modified.
.TP
.I ~/.zshrc
Zsh shell configuration file that may be modified.
.TP
.I ~/.profile
Generic shell profile that may be modified if no specific shell is detected.
.SH ENVIRONMENT
.TP
.B PATH
The environment variable being managed.
.TP
.B SHELL
Used to identify the appropriate configuration file to update.
.TP
.B HOME
Used for expanding tildes (~) in paths and locating configuration files.
.SH BACKUP FORMAT
Backups are stored as JSON files with the following structure:
.PP
.nf
.RS
{
"timestamp": "20240421120000",
"path": "/usr/local/bin:/usr/bin:/bin:~/custom/bin"
}
.RE
.fi
.SH EXIT STATUS
.TP
.B 0
Success
.TP
.B 1
General error (e.g., invalid directory, permission denied)
.SH DIAGNOSTICS
pathmaster provides clear error messages for common issues:
.TP
- Invalid directory warnings
.TP
- Permission denied errors
.TP
- Missing backup files
.TP
- Shell configuration update failures
.SH BUGS
Report bugs to: https://github.com/jwliles/pathmaster/issues
.SH AUTHOR
Justin Wayne Liles
.SH COPYRIGHT
Copyright (c) 2024 Justin Wayne Liles.
This is free software: you are free to change and redistribute it under the MIT License.
.SH SEE ALSO
.BR bash (1),
.BR zsh (1),
.BR env (1),
.BR path (7)
.SH NOTES
.PP
- Backups are created automatically before any PATH modification
.PP
- Shell configuration files are updated to make changes persistent
.PP
- Tilde (~) is automatically expanded to the user's home directory
.PP
- Directories are validated before being added to PATH
.PP
- PATH entries are kept unique (no duplicates)