docs: rewrite README usage and examples

.continue/rules/project.md

@@ -11,15 +11,8 @@ description: SSHRM project conventions
 - Prefer minimal, focused changes that do not alter the intent of the existing scripts, unless the script behavior is intentionally updated.
 - Maintain `.continue/rules/project.md` whenever project conventions or script behavior change.
 - `sshrm` is implemented as a small Bash script with helper functions, while preserving host and line-number removal behavior.
-- `sshrm` should print a short usage line, support `-h`/`--help`, and fail clearly on missing or invalid line-number input.
+- `sshrm` should print a short usage line, support `-h`/`--help`, fail clearly on missing or invalid line-number input, reject extra arguments, may support a dedicated `--no-backup` option with a `known_hosts.sshrm.bak` backup file, and now asks for confirmation before removal.
 
 # Project identity
 - Main script: `sshrm`
 - License: GNU GPL v3
-
-git checkout "${TAGBRANCH}"
-git merge "${CURRENTBRANCH}"
-git push
-git tag -a "${VERSION}" -m "${MESSAGE}"
-git push --tags
-git checkout "${CURRENTBRANCH}"

README.md

@@ -1,2 +1,42 @@
 # sshrm
 
+Remove an entry from `~/.ssh/known_hosts` by host name or by line number.
+
+## Usage
+
+```bash
+sshrm [-h|--help] [--no-backup] host|line_number
+```
+
+## Options
+
+- `-h`, `--help` Show help and exit.
+- `--no-backup` Skip creating `~/.ssh/known_hosts.sshrm.bak`.
+
+## Examples
+
+Remove by host:
+
+```bash
+sshrm example.com
+```
+
+Remove by line number:
+
+```bash
+sshrm 12
+```
+
+Remove without backup:
+
+```bash
+sshrm --no-backup example.com
+```
+
+## Notes
+
+- Line numbers must be positive integers.
+- Extra arguments are rejected.
+- The script asks for confirmation before removal.
+- The script edits `~/.ssh/known_hosts`.
+- Keep a backup if you need to recover entries.

sshrm

@@ -1,8 +1,9 @@
 #!/bin/bash
 
-set -u
+set -euo pipefail
 
 readonly FILENAME="${HOME}/.ssh/known_hosts"
+readonly BACKUP_FILE="${FILENAME}.sshrm.bak"
 
 check_known_hosts() {
 	if [ ! -f "${FILENAME}" ]; then
@@ -12,7 +13,7 @@ check_known_hosts() {
 }
 
 usage() {
-	echo "Usage: sshrm [-h|--help] host|line_number"
+	echo "Usage: sshrm [-h|--help] [--no-backup] host|line_number"
 }
 
 error() {
@@ -30,10 +31,28 @@ get_host_from_line() {
 	awk -v line="$1" 'NR == line {print $1; exit}' "${FILENAME}"
 }
 
+create_backup() {
+	cp "${FILENAME}" "${BACKUP_FILE}"
+}
+
 remove_host() {
 	ssh-keygen -R "$1"
 }
 
+confirm() {
+	local prompt="$1"
+	read -r -p "Remove ${prompt}? [y/N] " answer
+	case "$answer" in
+		y|Y|yes|YES)
+			return 0
+			;;
+		*)
+			error "cancelled."
+			return 1
+			;;
+	esac
+}
+
 if [ "${1-}" = "" ]; then
 	error "missing argument."
 	usage
@@ -45,9 +64,31 @@ if [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
 	exit 0
 fi
 
+backup=true
+if [ "$1" = "--no-backup" ]; then
+	backup=false
+	shift
+fi
+
+if [ "${1-}" = "" ]; then
+	error "missing argument."
+	usage
+	exit 1
+fi
+
+if [ "${2-}" != "" ]; then
+	error "too many arguments."
+	usage
+	exit 1
+fi
+
 check_known_hosts
 
 if is_number "$1"; then
+	if [ "$1" -eq 0 ]; then
+		error "invalid line number."
+		exit 1
+	fi
 	HOST="$(get_host_from_line "$1")"
 	if [ "${HOST}" = "" ]; then
 		error "invalid line number."
@@ -57,4 +98,15 @@ else
 	HOST="$1"
 fi
 
-remove_host "$HOST"
+if ! confirm "$HOST"; then
+	exit 1
+fi
+
+if [ "${backup}" = true ]; then
+	create_backup
+fi
+
+if ! remove_host "$HOST"; then
+	error "removal failed."
+	exit 1
+fi