claude-settings/commands/script-install.md

Install System Script

Create and install a system script with proper permissions and structure.

Steps

1. Understand the script requirements:

   • What does the script do?
   • Where should it be installed? (/usr/local/bin for system-wide)
   • Does it need root privileges?
   • Should it have ZSH completion?

2. Create the script with POSIX sh compliance:

   #!/bin/sh
   # Script: <name>
   # Description: <purpose>
   # Usage: <command> [options]
   
   set -eu  # errexit, nounset
   
   # Constants
   SCRIPT_NAME="$(basename "$0")"
   
   # Functions (before use)
   usage() {
     cat <<EOF
   Usage: ${SCRIPT_NAME} [options]
   
   Options:
     -h, --help    Show this help message
   
   Examples:
     ${SCRIPT_NAME} --option value
   EOF
     exit 0
   }
   
   # Main logic
   main() {
     # Implementation here
     :
   }
   
   # Parse arguments
   while [ $# -gt 0 ]; do
     case "$1" in
       -h|--help) usage ;;
       *) echo "Unknown option: $1"; usage ;;
     esac
     shift
   done
   
   main
   

3. Validate POSIX compliance:

   shellcheck -s sh <script>
   checkbashisms <script>
   

4. Test the script locally:

   chmod +x <script>
   ./<script> --help
   # Test actual functionality
   

5. Install system-wide:

   sudo install -m 0755 <script> /usr/local/bin/<name>
   

6. Create ZSH completion (if interactive): Create /usr/share/zsh/site-functions/_<name>:

   #compdef <name>
   
   _<name>() {
     local -a options
     options=(
       '--help[Show help message]'
       '--option[Description]:value'
     )
     _arguments -s $options
   }
   
   _<name> "$@"
   

7. Install completion:

   sudo install -m 0644 _<name> /usr/share/zsh/site-functions/_<name>
   

8. Reload ZSH completions:

   rm -f ~/.zcompdump
   compinit
   

9. Create OpenRC service (if needed): Create /etc/init.d/<name>:

   #!/sbin/openrc-run
   
   description="<Service description>"
   command="/usr/local/bin/<name>"
   command_args=""
   pidfile="/run/${RC_SVCNAME}.pid"
   
   depend() {
     need net
     after logger
   }
   

10. Enable service:

    sudo chmod +x /etc/init.d/<name>
    sudo rc-update add <name> default
    sudo rc-service <name> start
    

POSIX sh Rules

• Use [ ] NOT [[ ]]
• Quote all variables: "${var}"
• Use command -v instead of which
• No arrays (use newline-separated strings)
• Use $(command) not backticks
• Set -eu for safety
• Test with shellcheck

Security Considerations

• Never hardcode secrets
• Validate all inputs
• Use proper file permissions (0755 for executables, 0644 for configs)
• Log to appropriate location
• Handle errors gracefully
• Provide meaningful error messages

Documentation

Update relevant documentation:

• Add to docs/reference/USER-GUIDE.md for quick reference
• Create detailed guide in docs/guides/system/ if complex
• Update CLAUDE.md with script location and purpose
• Add to README.md if it's a major feature