Add support for JSON output

CHANGELOG.md

@@ -6,6 +6,13 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-02-06
+
+### Features
+
+- **JSON Output**: Added `--json` flag to output scan results in structured JSON format
+- **File Output**: Added `-o` / `--output` flag to save results to a file (supports both text and JSON)
+
 ### Fixed
 
 - PyPy on Windows now works gracefully when `shutil.disk_usage` is unavailable (displays message instead of crashing)

README.md

@@ -7,7 +7,7 @@ A CLI tool to discover what's hogging your disk space!
 
 The tool shows the largest files in each category of files (videos, pictures, documents etc.) as well as the largest special directories as apps in MacOS, Python virtual environments, node_modules etc.
 
-It's built to indentify the biggest chunks of data that could potentially free up the space for something else.
+It's built to identify the biggest chunks of data that could potentially free up the space for something else.
 
 ## Features
 
@@ -71,11 +71,20 @@ zpace .
 # Show top 20 items per category (default: 10)
 zpace -n 20
 
-# Set minimum file size to 1MB (default: 100KB)
+# Set minimum file size to 1MB (default: 100KB, value is in KB)
 zpace -m 1024
 
 # Combine options
 zpace ~/Documents -n 15 -m 500
+
+# Save results to a text file
+zpace -o results.txt
+
+# Output in JSON format
+zpace --json
+
+# Save JSON results to a file
+zpace --json -o results.json
 ```
 
 ### Example Output
@@ -335,6 +344,42 @@ Videos (10 files)
 ```
 </details>
 
+<details>
+<summary>Open JSON example output</summary>
+
+```json
+{
+  "version": "1.0",
+  "scan_path": "/Users/azis",
+  "timestamp": "2026-01-28T14:30:00Z",
+  "disk_usage": {
+    "total_bytes": 926350000000,
+    "used_bytes": 393340000000,
+    "free_bytes": 533010000000,
+    "used_percent": 42.5,
+    "trash_bytes": 310410000
+  },
+  "scan_summary": {
+    "total_files": 593044,
+    "special_directories": 420,
+    "total_size_bytes": 208580000000
+  },
+  "special_directories": {
+    "Node Modules": [
+      {"path": "/path/to/node_modules", "size_bytes": 1120000000}
+    ],
+    "Virtual Environments": [...]
+  },
+  "files_by_category": {
+    "Videos": [
+      {"path": "/path/to/video.mov", "size_bytes": 986900000}
+    ],
+    "Archives": [...]
+  }
+}
+```
+</details>
+
 ### Configuration
 
 Zpace can be customized via `~/.zpace.toml`. See [.zpace.toml.sample](.zpace.toml.sample) for a template:
@@ -462,11 +507,14 @@ zpace/
 │   ├── main.py
 │   ├── core.py
 │   ├── config.py
-│   └── utils.py
-├── main.py           # Entry point
-├── pyproject.toml    # Project configuration
-├── README.md         # This file
-└── CHANGELOG.md      # Version history
+│   ├── utils.py
+│   └── output.py
+├── main.py              # Entry point
+├── test_unit.py         # Unit tests
+├── test_integration.py  # Integration tests
+├── pyproject.toml       # Project configuration
+├── README.md            # This file
+└── CHANGELOG.md         # Version history
 ```
 
 ### Contributing

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "zpace"
-version = "0.4.5"
+version = "0.5.0"
 description = "A CLI tool to discover what's consuming your disk space"
 readme = "README.md"
 requires-python = ">=3.9"