Upload

docs/cli.md

@@ -1,45 +1,55 @@
-# Klangkiste Box CLI
+# Box CLI Reference
 
-This document lists all currently available CLI interactions (Phase 1a).
+## Purpose
+List all CLI interactions available in the virtual box.
 
-## Commands
+## Prerequisites
+- Box code available in `box/`
 
-### status
-Show the current runtime status.
-
-Example:
+## Step-by-step
+### One-shot commands
+Status:
 ```
-python box/main.py status
+python3 box/main.py status
 ```
 
-### simulate-nfc <uid>
-Simulate NFC tag detection. Resolves the UID to a playback object from `box/config/box_config.json` and starts playback.
-
-Example:
+Simulate NFC:
 ```
-python box/main.py simulate-nfc CHIP_1
+python3 box/main.py simulate-nfc UID_1
+python3 box/main.py simulate-nfc-off UID_1
 ```
 
-### simulate-nfc-off <uid>
-Simulate NFC tag removal. Stops playback and stores progress for that UID.
-
-Example:
+Manual tick:
 ```
-python box/main.py simulate-nfc-off CHIP_1
+python3 box/main.py tick 30
 ```
 
-### tick <seconds>
-Simulate playback time progression. Advances position and moves to next file when a file ends.
-
-Example:
+### Interactive run mode
 ```
-python box/main.py tick 90
+python3 box/main.py run
+```
+Commands inside run mode:
+```
+status
+nfc <UID>
+nfc-off <UID>
+tick <seconds>
+play | pause
+next | vor
+prev | zurueck
+vol-up | lauter
+vol-down | leiser
+help
+exit | quit
 ```
 
-### run
-Start an interactive session that keeps state in memory. Use `help` inside the session for available commands.
+## Checklist
+- ✅ `status` prints runtime state
+- ✅ `simulate-nfc` starts playback
+- ✅ `run` accepts interactive commands
 
-Example:
-```
-python box/main.py run
-```
+## Troubleshooting
+- Commands not found:
+  - Ensure you run from repo root or use full path to `box/main.py`.
+- No playback:
+  - Check tags in `box/data/box.json` and media under `box/data/media`.