docs: add documentation for awf logs command (#73)

* Initial plan

* docs: add documentation for awf logs command

Co-authored-by: Mossaka <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: Mossaka <[email protected]>

Author: Copilot

README.md

@@ -52,6 +52,24 @@ sudo awf \
 
 **Note:** Always use the `--` separator to pass commands and arguments. This ensures proper argument handling and avoids shell escaping issues.
 
+### Log Viewing
+
+View Squid proxy logs from current or previous runs:
+
+```bash
+# View recent logs with pretty formatting
+awf logs
+
+# Follow logs in real-time
+awf logs -f
+
+# View logs in JSON format for scripting
+awf logs --format json
+
+# List all available log sources
+awf logs --list
+```
+
 ## Domain Whitelisting
 
 Domains automatically match all subdomains:

docs-site/src/content/docs/reference/cli-reference.md

@@ -139,6 +139,59 @@ Working directory inside the container.
 | `130` | Interrupted by SIGINT (Ctrl+C) |
 | `143` | Terminated by SIGTERM |
 
+## Subcommands
+
+### `awf logs`
+
+View Squid proxy logs from current or previous runs.
+
+```bash
+awf logs [options]
+```
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `-f, --follow` | flag | `false` | Follow log output in real-time |
+| `--format <format>` | string | `pretty` | Output format: `raw`, `pretty`, `json` |
+| `--source <path>` | string | auto | Path to log directory or `running` for live container |
+| `--list` | flag | `false` | List available log sources |
+
+#### Output Formats
+
+| Format | Description |
+|--------|-------------|
+| `pretty` | Colorized, human-readable output (default) |
+| `raw` | Logs as-is without parsing |
+| `json` | Structured JSON for scripting |
+
+#### Examples
+
+```bash
+# View recent logs with pretty formatting
+awf logs
+
+# Follow logs in real-time
+awf logs -f
+
+# View logs in JSON format
+awf logs --format json
+
+# List available log sources
+awf logs --list
+
+# Use a specific log directory
+awf logs --source /tmp/squid-logs-1234567890
+
+# Stream from running container
+awf logs --source running -f
+```
+
+:::note
+Log sources are auto-discovered in this order: running containers, `AWF_LOGS_DIR` environment variable, then preserved log directories in `/tmp/squid-logs-*`.
+:::
+
 ## See Also
 
 - [Quick Start Guide](/gh-aw-firewall/quickstart) - Getting started with examples

docs/usage.md

@@ -353,6 +353,99 @@ docker logs awf-squid
 # /tmp/awf-<timestamp>/squid-logs/
 ```
 
+## Viewing Logs with `awf logs`
+
+The `awf logs` command provides an easy way to view Squid proxy logs from current or previous runs.
+
+### Basic Usage
+
+```bash
+# View recent logs with pretty formatting (default)
+awf logs
+
+# Follow logs in real-time (like tail -f)
+awf logs -f
+```
+
+### Output Formats
+
+The command supports three output formats:
+
+```bash
+# Pretty: colorized, human-readable output (default)
+awf logs --format pretty
+
+# Raw: logs as-is without parsing or colorization
+awf logs --format raw
+
+# JSON: structured output for programmatic consumption
+awf logs --format json
+```
+
+Example JSON output:
+```json
+{"timestamp":1760987995.318,"clientIp":"172.20.98.20","clientPort":"55960","domain":"example.com","destIp":"-","destPort":"-","httpVersion":"1.1","method":"CONNECT","statusCode":403,"decision":"TCP_DENIED:HIER_NONE","url":"example.com:443","userAgent":"curl/7.81.0","isAllowed":false}
+```
+
+### Log Source Discovery
+
+The command auto-discovers log sources in this order:
+1. Running `awf-squid` container (live logs)
+2. `AWF_LOGS_DIR` environment variable (if set)
+3. Preserved log directories in `/tmp/squid-logs-<timestamp>`
+
+```bash
+# List all available log sources
+awf logs --list
+
+# Output example:
+# Available log sources:
+#   [running] awf-squid (live container)
+#   [preserved] /tmp/squid-logs-1760987995318 (11/27/2024, 12:30:00 PM)
+#   [preserved] /tmp/squid-logs-1760987890000 (11/27/2024, 12:28:10 PM)
+```
+
+### Using Specific Log Sources
+
+```bash
+# Stream from a running container
+awf logs --source running -f
+
+# Use a specific preserved log directory
+awf logs --source /tmp/squid-logs-1760987995318
+
+# Use logs from AWF_LOGS_DIR
+export AWF_LOGS_DIR=/path/to/logs
+awf logs
+```
+
+### Combining Options
+
+```bash
+# Follow live logs in JSON format
+awf logs -f --format json
+
+# View specific logs in raw format
+awf logs --source /tmp/squid-logs-1760987995318 --format raw
+```
+
+### Troubleshooting with Logs
+
+**Find blocked requests:**
+```bash
+awf logs --format json | jq 'select(.isAllowed == false)'
+```
+
+**Filter by domain:**
+```bash
+awf logs --format json | jq 'select(.domain | contains("github"))'
+```
+
+**Count blocked vs allowed:**
+```bash
+awf logs --format json | jq -s 'group_by(.isAllowed) | map({allowed: .[0].isAllowed, count: length})'
+```
+
 ## Log Analysis
 
 Find all blocked domains: