diff --git a/README.md b/README.md
index f62f062..8a29ede 100644
--- a/README.md
+++ b/README.md
@@ -67,6 +67,14 @@ The first `install <source>` scans the source for agent files, installs them int
 
 ## Commands
 
+### Global Options
+
+These options can be used with any command:
+
+| Option | Description |
+|---|---|
+| `-v, --verbose` | Enable debug logging output for troubleshooting |
+
 ### `agentfiles init`
 
 Create a new `agentfiles.json` manifest. The manifest starts empty -- add dependencies with `agentfiles install <source>`.
@@ -173,6 +181,9 @@ agentfiles scan
 
 # Scan a remote repository
 agentfiles scan github.com/org/repo@main
+
+# Scan with verbose output for troubleshooting
+agentfiles --verbose scan github.com/org/repo
 ```
 
 ### `agentfiles list`
diff --git a/src/cli.rs b/src/cli.rs
index b10f3bd..76fec8e 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -11,6 +11,7 @@ use crate::types::{AgentProvider, FileScope, FileStrategy};
     version
 )]
 pub struct Cli {
+    /// Enable debug logging output
     #[arg(short, long, global = true)]
     pub verbose: bool,