docs: add CLI reference and update terminal usage guide

Author: mohitgauniyal

README.md

@@ -189,6 +189,8 @@ The difference between *a tool you use* and *a tool you own.*
 
 **Security hardened** — rate limiting on all write endpoints, magic number file validation, filename sanitisation, and forced download for executable file types.
 
+**CLI companion** — `instbyte send`, `instbyte watch`, and `instbyte status` let you push files, pipe command output, sync clipboard, and check server health without opening a browser. Auto-discovers the running server from your working directory.
+
 ---
 
 ## Broadcasting
@@ -220,7 +222,7 @@ For HTTPS setup and advanced network configuration, see the [Deployment Guide](d
 git clone https://github.com/mohitgauniyal/instbyte
 cd instbyte
 npm install
-node server/server.js
+node bin/instbyte.js
 ```
 
 ---
@@ -237,9 +239,19 @@ node server/server.js
 
 ---
 
-## Terminal Usage
+## CLI & Terminal Usage
+
+Send files, pipe command output, watch channels, and check server status from your terminal — no browser needed.
+
+```bash
+instbyte send ./build.zip --channel assets
+instbyte send "http://staging.myapp.com"
+git log --oneline -20 | instbyte send
+instbyte watch --channel projects
+instbyte status
+```
 
-Push content from your terminal using curl — no browser needed. See [Terminal Usage Guide](docs/terminal-usage.md).
+See the [Terminal Usage Guide](docs/terminal-usage.md) for the full CLI reference, CI/CD setup, and raw curl fallback.
 
 ---
 
@@ -253,7 +265,7 @@ Instbyte follows [Semantic Versioning](https://semver.org). See [Releases](https
 
 Instbyte is intentionally lightweight and LAN-first. If you want to extend it — CLI tools, themes, integrations — open an issue or submit a pull request.
 
-The codebase has a full test suite (195 tests across unit and integration). Run `npm test` before submitting anything. Issues tagged **good first issue** are a good starting point.
+The codebase has a full test suite (214 tests across unit and integration). Run `npm test` before submitting anything. Issues tagged **good first issue** are a good starting point.
 
 ---
 

docs/terminal-usage.md

@@ -1,116 +1,138 @@
 # Terminal Usage
 
-Instbyte exposes a simple HTTP API — push content directly from your terminal using `curl`, no browser needed.
+Instbyte has a first-class CLI for sending, watching, and checking server status — no browser needed.
 
-Replace `192.168.x.x:3000` with the URL shown when Instbyte starts.
+Replace `192.168.x.x:3000` with the URL shown when Instbyte starts. If you're working in the same directory (or any subdirectory) as where the server was started, the URL is discovered automatically.
 
 ---
 
-## Send text or a link
+## CLI
+
+### Send a file
 ```bash
-curl -X POST http://192.168.x.x:3000/push \
-  -H "Content-Type: text/plain" \
-  -d "hello from terminal"
+instbyte send ./build.zip
+instbyte send ./error.log --channel projects
+instbyte send ./report.pdf --channel assets --passphrase myteam
 ```
 
-Use `X-Channel` and `X-Uploader` headers to control where it lands. Both default to `general` and `terminal` if omitted.
+### Send text or a link
 ```bash
-curl -X POST http://192.168.x.x:3000/push \
-  -H "Content-Type: text/plain" \
-  -H "X-Channel: projects" \
-  -H "X-Uploader: mohit" \
-  -d "targeted push"
+instbyte send "http://staging.myapp.com"
+instbyte send "quick note for the team" --channel projects
 ```
 
----
+### Pipe anything in
+```bash
+npm run build 2>&1 | instbyte send
+git log --oneline -20 | instbyte send
+docker logs my-container | instbyte send --channel projects
+cat error.log | instbyte send
+```
 
-## Pipe command output
+> Windows: use PowerShell or CMD for piping. Git Bash has a known stdin limitation with native executables.
 
-Any command output — logs, build errors, git history — pipes directly. No quoting or escaping needed.
+### Watch a channel — auto-copy new text to clipboard
 ```bash
-# build output
-npm run build 2>&1 | curl -X POST http://192.168.x.x:3000/push \
-  -H "Content-Type: text/plain" \
-  --data-binary @-
-
-# directory listing
-ls -la | curl -X POST http://192.168.x.x:3000/push \
-  -H "Content-Type: text/plain" \
-  --data-binary @-
+instbyte watch                     # watches general channel
+instbyte watch --channel projects  # specific channel
+instbyte watch --output            # print to stdout instead of clipboard
+instbyte watch --output | grep "error"  # pipeable
+```
 
-# git log
-git log --oneline -20 | curl -X POST http://192.168.x.x:3000/push \
-  -H "Content-Type: text/plain" \
-  --data-binary @-
+New text items are silently copied to your clipboard. File items print the download URL.
 
-# docker logs
-docker logs my-container 2>&1 | curl -X POST http://192.168.x.x:3000/push \
-  -H "Content-Type: text/plain" \
-  --data-binary @-
+### Check server status
+```bash
+instbyte status
+instbyte status --server http://192.168.x.x:3000
 ```
 
 ---
 
-## Send a file's contents as text
-```bash
-curl -X POST http://192.168.x.x:3000/push \
-  -H "Content-Type: text/plain" \
-  --data-binary @error.log
-```
+## Server auto-discovery
 
-This works for any text file — logs, configs, `.env` snapshots, stack traces. The content appears in the feed with syntax highlighting if the extension is recognised.
+When the server starts, it writes a small runtime config to `instbyte-data/.runtime.json` with the server URL and passphrase. The CLI picks this up automatically by walking up from your current directory — the same way git finds `.git`.
 
-> Use `/upload` instead if you want the file itself to be downloadable rather than read inline.
+Priority order for every CLI command:
+1. `--server` / `--passphrase` flags
+2. `INSTBYTE_URL` / `INSTBYTE_PASS` environment variables
+3. `instbyte-data/.runtime.json` found by walking up from cwd
+4. `http://localhost:3000` fallback
 
 ---
 
-## Upload a file
+## CI/CD
+
+Environment variables are the clean path for CI — set once as a secret, use everywhere:
 
-Any file type — images, PDFs, zips, executables, media.
 ```bash
-curl -X POST http://192.168.x.x:3000/upload \
-  -F "file=@./screenshot.png" \
-  -F "channel=general" \
-  -F "uploader=terminal"
+# Set in CI environment
+INSTBYTE_URL=http://192.168.x.x:3000
+INSTBYTE_PASS=myteam
 ```
 
----
-
-## With auth enabled
-
-Pass the passphrase as a header — works from any terminal or CI environment without needing a browser session.
-```bash
-curl -X POST http://192.168.x.x:3000/push \
-  -H "Content-Type: text/plain" \
-  -H "X-Passphrase: yourpassword" \
-  --data-binary @error.log
+```yaml
+# GitHub Actions
+- name: Share build artifact
+  run: npx instbyte send ./dist/app.zip --channel assets
 ```
 
-All endpoints accept `X-Passphrase`. Upload too:
-```bash
-curl -X POST http://192.168.x.x:3000/upload \
-  -H "X-Passphrase: yourpassword" \
-  -F "file=@./build.zip" \
-  -F "channel=assets" \
-  -F "uploader=CI"
+```json
+// package.json scripts
+{
+  "scripts": {
+    "build": "webpack && instbyte send ./dist/build.zip --channel assets",
+    "test": "vitest run 2>&1 | instbyte send --channel projects"
+  }
+}
 ```
 
 ---
 
-## Quick reference — headers
+## Options
 
-| Header | Applies to | Default | Description |
+| Flag | Commands | Default | Description |
 |---|---|---|---|
-| `X-Channel` | `/push`, `/text` | `general` | Channel to post into |
-| `X-Uploader` | `/push`, `/text` | `terminal` | Display name in the feed |
-| `X-Passphrase` | all endpoints | — | Passphrase if auth is enabled |
+| `--server <url>` | all | auto-discovered | Server URL |
+| `--channel <name>` | send, watch | `general` | Target channel |
+| `--passphrase <pass>` | all | auto-discovered | Passphrase if auth is enabled |
+| `--uploader <name>` | send | OS username | Display name for sent items |
+| `--output` | watch | — | Print to stdout instead of clipboard |
+| `--quiet` | send | — | Suppress confirmation output |
 
 ---
 
-## Use cases
+## Raw HTTP (curl)
 
-- Pipe stack traces or build output from CI straight into a shared channel
-- Send `.env` snapshots or config dumps from a remote server
-- Push deployment notifications to a team channel
-- Share API responses or debug output without leaving the terminal
-```
+The HTTP API is also available directly — useful for environments without the CLI installed.
+
+```bash
+# Send text
+curl -X POST http://192.168.x.x:3000/push \
+  -H "Content-Type: text/plain" \
+  -d "hello from terminal"
+
+# Send to a specific channel
+curl -X POST http://192.168.x.x:3000/push \
+  -H "Content-Type: text/plain" \
+  -H "X-Channel: projects" \
+  -H "X-Uploader: mohit" \
+  -d "targeted push"
+
+# Pipe command output
+npm run build 2>&1 | curl -X POST http://192.168.x.x:3000/push \
+  -H "Content-Type: text/plain" \
+  --data-binary @-
+
+# Upload a file
+curl -X POST http://192.168.x.x:3000/upload \
+  -F "file=@./screenshot.png" \
+  -F "channel=general" \
+  -F "uploader=terminal"
+
+# With auth
+curl -X POST http://192.168.x.x:3000/push \
+  -H "Content-Type: text/plain" \
+  -H "X-Passphrase: yourpassword" \
+  --data-binary @error.log
+```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "instbyte",
-  "version": "1.11.1",
+  "version": "1.12.0",
   "description": "A self-hosted LAN sharing utility for fast, frictionless file, link, and snippet exchange across devices — no cloud required.",
   "main": "bin/instbyte.js",
   "bin": {