diff --git a/README.md b/README.md
index bdf6388..2fccf2e 100644
--- a/README.md
+++ b/README.md
@@ -121,6 +121,7 @@ Each app has detailed documentation in its own directory:
- [`mac-cache-cleaner/README.md`](mac-cache-cleaner/README.md) - Full mac-cache-cleaner docs
- [`dev-cache/README.md`](dev-cache/README.md) - Full dev-cache docs
- [`git-cleaner/README.md`](git-cleaner/README.md) - Full git-cleaner docs
+- [`docs/scheduling.md`](docs/scheduling.md) - cron and launchd scheduling examples
## Development
diff --git a/dev-cache/main.go b/dev-cache/main.go
index 4fb7b18..f89df5e 100644
--- a/dev-cache/main.go
+++ b/dev-cache/main.go
@@ -37,6 +37,19 @@ var (
flagLangs = flag.String("languages", "", "Comma-separated list of languages to scan")
)
+func init() {
+ flag.Usage = func() {
+ out := flag.CommandLine.Output()
+ fmt.Fprintf(out, "Usage: dev-cache [flags]\n\nFlags:\n")
+ flag.PrintDefaults()
+ fmt.Fprintf(out, "\nExamples:\n")
+ fmt.Fprintf(out, " dev-cache # Scan default path from config\n")
+ fmt.Fprintf(out, " dev-cache --scan ~/projects # Scan specific directory\n")
+ fmt.Fprintf(out, " dev-cache --clean --yes # Clean without confirmation\n")
+ fmt.Fprintf(out, " dev-cache --languages node,rust # Only node and rust caches\n")
+ }
+}
+
// ----- Config types -----
type Config struct {
diff --git a/docs/scheduling.md b/docs/scheduling.md
new file mode 100644
index 0000000..1b4ef94
--- /dev/null
+++ b/docs/scheduling.md
@@ -0,0 +1,70 @@
+# Scheduled Runs
+
+Use scheduled jobs to run cache cleanup during low-usage hours.
+
+## cron (Linux/macOS)
+
+Weekly at 3:00 AM every Sunday:
+
+```cron
+0 3 * * 0 /usr/local/bin/dev-cache --scan ~/src --clean --yes >> ~/cache-cleaner.log 2>&1
+0 3 * * 0 /usr/local/bin/git-cleaner --scan ~/src --clean >> ~/cache-cleaner.log 2>&1
+0 3 * * 0 /usr/local/bin/mac-cache-cleaner --clean >> ~/cache-cleaner.log 2>&1
+```
+
+Notes:
+- Update binary paths based on your install location (`which dev-cache`, `which git-cleaner`, `which mac-cache-cleaner`).
+- Keep log redirection enabled for troubleshooting.
+
+## launchd (macOS)
+
+Create `~/Library/LaunchAgents/com.cache-cleaner.weekly.plist`:
+
+```xml
+
+
+
+
+ Label
+ com.cache-cleaner.weekly
+
+ ProgramArguments
+
+ /usr/local/bin/mac-cache-cleaner
+ --clean
+
+
+ StartCalendarInterval
+
+ Weekday
+ 1
+ Hour
+ 3
+ Minute
+ 0
+
+
+ StandardOutPath
+ /Users/YOUR_USER/cache-cleaner.log
+ StandardErrorPath
+ /Users/YOUR_USER/cache-cleaner.log
+
+
+```
+
+Load and start:
+
+```bash
+launchctl load ~/Library/LaunchAgents/com.cache-cleaner.weekly.plist
+launchctl start com.cache-cleaner.weekly
+```
+
+Unload:
+
+```bash
+launchctl unload ~/Library/LaunchAgents/com.cache-cleaner.weekly.plist
+```
+
+## Homebrew services
+
+`brew services` is best for long-running daemons, not periodic CLI jobs. For periodic cleanup, prefer `cron` or `launchd`.
diff --git a/git-cleaner/main.go b/git-cleaner/main.go
index c02c8b2..7f4fea8 100644
--- a/git-cleaner/main.go
+++ b/git-cleaner/main.go
@@ -27,6 +27,17 @@ var (
flagClean = flag.Bool("clean", false, "Run git gc in each repository and show disk savings")
)
+func init() {
+ flag.Usage = func() {
+ out := flag.CommandLine.Output()
+ fmt.Fprintf(out, "Usage: git-cleaner --scan [flags]\n\nFlags:\n")
+ flag.PrintDefaults()
+ fmt.Fprintf(out, "\nExamples:\n")
+ fmt.Fprintf(out, " git-cleaner --scan ~/src # Scan for .git directories\n")
+ fmt.Fprintf(out, " git-cleaner --scan ~/src --clean # Optimize with git gc\n")
+ }
+}
+
// ----- Finding types -----
type Finding struct {
diff --git a/mac-cache-cleaner/main.go b/mac-cache-cleaner/main.go
index 4791992..04fa5c2 100644
--- a/mac-cache-cleaner/main.go
+++ b/mac-cache-cleaner/main.go
@@ -65,6 +65,18 @@ var (
flagDetails = flag.Bool("details", false, "Show detailed per-directory information")
)
+func init() {
+ flag.Usage = func() {
+ out := flag.CommandLine.Output()
+ fmt.Fprintf(out, "Usage: mac-cache-cleaner [flags]\n\nFlags:\n")
+ flag.PrintDefaults()
+ fmt.Fprintf(out, "\nExamples:\n")
+ fmt.Fprintf(out, " mac-cache-cleaner # Scan all targets (dry-run)\n")
+ fmt.Fprintf(out, " mac-cache-cleaner --clean # Run cleanup commands\n")
+ fmt.Fprintf(out, " mac-cache-cleaner --targets docker,npm # Specific targets only\n")
+ }
+}
+
// ----- Config types -----
type Config struct {