instbyte 1.11.1 → 1.12.0

package/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.
 
 ---
 

package/bin/cli/resolve.js

@@ -0,0 +1,55 @@
+"use strict";
+
+const fs   = require("fs");
+const path = require("path");
+const os   = require("os");
+
+const RUNTIME_FILE = path.join("instbyte-data", ".runtime.json");
+
+// Walk up from dir looking for instbyte-data/.runtime.json.
+// Stops at the user's home directory.
+function findRuntimeConfig(dir) {
+  const candidate = path.join(dir, RUNTIME_FILE);
+  if (fs.existsSync(candidate)) {
+    try { return JSON.parse(fs.readFileSync(candidate, "utf-8")); }
+    catch { return null; }
+  }
+
+  const parent = path.dirname(dir);
+  if (parent === dir || dir === os.homedir()) return null; // reached root or home
+
+  return findRuntimeConfig(parent);
+}
+
+// Returns { url, passphrase } for CLI commands.
+// Priority: explicit flags → env vars → .runtime.json walk → localhost fallback
+function resolveServer(flags = {}) {
+  if (flags.server) {
+    return {
+      url:        flags.server.replace(/\/$/, ""),
+      passphrase: flags.passphrase || process.env.INSTBYTE_PASS || ""
+    };
+  }
+
+  if (process.env.INSTBYTE_URL) {
+    return {
+      url:        process.env.INSTBYTE_URL.replace(/\/$/, ""),
+      passphrase: flags.passphrase || process.env.INSTBYTE_PASS || ""
+    };
+  }
+
+  const runtime = findRuntimeConfig(process.cwd());
+  if (runtime && runtime.url) {
+    return {
+      url:        runtime.url,
+      passphrase: flags.passphrase || runtime.passphrase || ""
+    };
+  }
+
+  return {
+    url:        "http://localhost:3000",
+    passphrase: flags.passphrase || ""
+  };
+}
+
+module.exports = { resolveServer, findRuntimeConfig };

package/bin/cli/send.js

@@ -0,0 +1,161 @@
+"use strict";
+
+const fs   = require("fs");
+const path = require("path");
+const os   = require("os");
+
+const { resolveServer } = require("./resolve");
+
+// argv after 'send'
+const argv = process.argv.slice(3);
+
+function parseArgs(argv) {
+  const flags = {};
+  let positional = null;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const key  = arg.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else if (positional === null) {
+      positional = arg;
+    }
+  }
+
+  return { flags, positional };
+}
+
+// Null byte in the first 512 bytes → binary
+function isBinary(buf) {
+  const limit = Math.min(buf.length, 512);
+  for (let i = 0; i < limit; i++) {
+    if (buf[i] === 0) return true;
+  }
+  return false;
+}
+
+// fs.readFileSync(0) reads fd 0 (stdin) synchronously — more portable than
+// event-based stream reading, and works correctly in Git Bash / MINGW64.
+function readStdin() {
+  return fs.readFileSync(0);
+}
+
+function fail(msg, hint) {
+  console.error(`✗ ${msg}`);
+  if (hint) console.error(`  ${hint}`);
+  process.exit(1);
+}
+
+async function run() {
+  const { flags, positional } = parseArgs(argv);
+
+  if (flags.help) {
+    console.log("Usage: instbyte send [<file|text>] [--channel <name>] [--server <url>] [--passphrase <pass>] [--uploader <name>] [--quiet]");
+    process.exit(0);
+  }
+
+  const { url, passphrase } = resolveServer(flags);
+  const channel  = flags.channel  || "general";
+  const uploader = flags.uploader || os.userInfo().username;
+  const quiet    = !!flags.quiet;
+
+  const authHeader = passphrase ? { "X-Passphrase": passphrase } : {};
+
+  // ── FILE ──────────────────────────────────────────────────────────────────
+  if (positional && fs.existsSync(positional)) {
+    const filePath = path.resolve(positional);
+    const filename = path.basename(filePath);
+
+    const form = new FormData();
+    form.append("file", new Blob([fs.readFileSync(filePath)]), filename);
+    form.append("channel",  channel);
+    form.append("uploader", uploader);
+
+    let res;
+    try {
+      res = await fetch(`${url}/upload`, { method: "POST", headers: authHeader, body: form });
+    } catch {
+      fail(
+        "Connection failed — is the server running?",
+        `Start with: npx instbyte\nOr specify: instbyte send ${positional} --server http://192.168.x.x:3000`
+      );
+    }
+
+    if (res.status === 401) fail("Unauthorized — wrong passphrase or auth required");
+    if (!res.ok) fail(`Server error: ${res.status}`);
+
+    if (!quiet) console.log(`✓ Sent to ${channel} — ${url}`);
+    process.exit(0);
+  }
+
+  // ── TEXT (positional arg that is not a file path) ─────────────────────────
+  if (positional) {
+    let res;
+    try {
+      res = await fetch(`${url}/push`, {
+        method: "POST",
+        headers: { ...authHeader, "Content-Type": "text/plain", "X-Channel": channel, "X-Uploader": uploader },
+        body: positional
+      });
+    } catch {
+      fail(
+        "Connection failed — is the server running?",
+        `Start with: npx instbyte\nOr specify: instbyte send "${positional}" --server http://192.168.x.x:3000`
+      );
+    }
+
+    if (res.status === 401) fail("Unauthorized — wrong passphrase or auth required");
+    if (!res.ok) fail(`Server error: ${res.status}`);
+
+    if (!quiet) console.log(`✓ Sent to ${channel} — ${url}`);
+    process.exit(0);
+  }
+
+  // ── STDIN ─────────────────────────────────────────────────────────────────
+  if (!process.stdin.isTTY) {
+    let buf;
+    try { buf = readStdin(); }
+    catch { fail("Failed to read stdin"); }
+
+    if (isBinary(buf)) {
+      fail("Binary stdin detected — use `instbyte send ./file` to upload a file");
+    }
+
+    const content = buf.toString("utf-8");
+    if (!content.trim()) fail("Empty input — nothing to send");
+
+    let res;
+    try {
+      res = await fetch(`${url}/push`, {
+        method: "POST",
+        headers: { ...authHeader, "Content-Type": "text/plain", "X-Channel": channel, "X-Uploader": uploader },
+        body: content
+      });
+    } catch {
+      fail(
+        "Connection failed — is the server running?",
+        "Start with: npx instbyte\nOr specify: instbyte send --server http://192.168.x.x:3000"
+      );
+    }
+
+    if (res.status === 401) fail("Unauthorized — wrong passphrase or auth required");
+    if (!res.ok) fail(`Server error: ${res.status}`);
+
+    if (!quiet) console.log(`✓ Sent to ${channel} — ${url}`);
+    process.exit(0);
+  }
+
+  // ── NO INPUT ──────────────────────────────────────────────────────────────
+  console.error("Usage: instbyte send <file|text>");
+  console.error("       cat file.log | instbyte send");
+  process.exit(1);
+}
+
+run();

package/bin/cli/status.js

@@ -0,0 +1,67 @@
+"use strict";
+
+const { resolveServer } = require("./resolve");
+
+const argv = process.argv.slice(3);
+
+function parseArgs(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const key  = arg.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) { flags[key] = next; i++; }
+      else flags[key] = true;
+    }
+  }
+  return flags;
+}
+
+function formatUptime(seconds) {
+  if (seconds < 60)   return `${seconds}s`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m`;
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  return m > 0 ? `${h}h ${m}m` : `${h}h`;
+}
+
+async function run() {
+  const flags = parseArgs(argv);
+
+  if (flags.help) {
+    console.log("Usage: instbyte status [--server <url>] [--passphrase <pass>]");
+    process.exit(0);
+  }
+
+  const { url, passphrase } = resolveServer(flags);
+  const headers = passphrase ? { "X-Passphrase": passphrase } : {};
+
+  let health, channels;
+
+  try {
+    const [hRes, cRes] = await Promise.all([
+      fetch(`${url}/health`, { headers }),
+      fetch(`${url}/channels`, { headers })
+    ]);
+
+    if (!hRes.ok) throw new Error(`${hRes.status}`);
+    health   = await hRes.json();
+    channels = await cRes.json();
+  } catch {
+    console.error(`✗ No Instbyte server found at ${url}`);
+    console.error(`  Start one with:  npx instbyte`);
+    console.error(`  Or specify:      instbyte status --server http://192.168.x.x:3000`);
+    process.exit(1);
+  }
+
+  const channelNames = channels.map(c => c.name).join(", ");
+
+  console.log(`✓ Instbyte v${health.version} running at ${url}`);
+  console.log(`  Uptime:    ${formatUptime(health.uptime)}`);
+  console.log(`  Connected: ${health.connected} user${health.connected !== 1 ? "s" : ""}`);
+  console.log(`  Channels:  ${channelNames}`);
+  if (health.hasAuth) console.log(`  Auth:      enabled`);
+}
+
+run();

package/bin/cli/watch.js

@@ -0,0 +1,124 @@
+"use strict";
+
+const { spawn }         = require("child_process");
+const os                = require("os");
+const { resolveServer } = require("./resolve");
+
+const argv = process.argv.slice(3);
+
+function parseArgs(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const key  = arg.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) { flags[key] = next; i++; }
+      else flags[key] = true;
+    }
+  }
+  return flags;
+}
+
+// Write text to the system clipboard.
+// Falls back to printing the text if the clipboard tool is not found.
+function copyToClipboard(text) {
+  let cmd, args;
+  if (process.platform === "darwin") {
+    cmd = "pbcopy"; args = [];
+  } else if (process.platform === "win32") {
+    cmd = "clip"; args = [];
+  } else {
+    cmd = "xclip"; args = ["-sel", "c"];
+  }
+
+  const proc = spawn(cmd, args, { stdio: ["pipe", "ignore", "ignore"] });
+  proc.on("error", () => process.stdout.write(text + "\n")); // fallback
+  proc.stdin.write(text, "utf-8");
+  proc.stdin.end();
+}
+
+function truncate(str, len) {
+  return str.length > len ? str.slice(0, len) + "…" : str;
+}
+
+function run() {
+  const flags = parseArgs(argv);
+
+  if (flags.help) {
+    console.log("Usage: instbyte watch [--channel <name>] [--server <url>] [--passphrase <pass>] [--output]");
+    process.exit(0);
+  }
+
+  const { url } = resolveServer(flags);
+  const channel    = flags.channel || "general";
+  const outputMode = !!flags.output;
+
+  // In --output mode, status messages go to stderr so stdout stays clean for piping
+  const status = outputMode
+    ? (msg) => process.stderr.write(msg + "\n")
+    : (msg) => process.stdout.write(msg + "\n");
+
+  const { io } = require("socket.io-client");
+
+  const socket = io(url, {
+    reconnection: true,
+    reconnectionDelay: 2000,
+    reconnectionDelayMax: 10000
+  });
+
+  let connected       = false;
+  let connectErrShown = false;
+  let stopping        = false;
+
+  socket.on("connect", () => {
+    socket.emit("join", os.userInfo().username);
+    status(connected
+      ? "Reconnected."
+      : `Watching ${channel} on ${url}... (Ctrl+C to stop)`
+    );
+    connected       = true;
+    connectErrShown = false;
+  });
+
+  socket.on("disconnect", () => {
+    if (stopping) return;
+    connected = false;
+    status("Reconnecting...");
+  });
+
+  socket.on("connect_error", () => {
+    if (!connectErrShown) {
+      status(`✗ Cannot connect to ${url}`);
+      status(`  Start a server with: npx instbyte`);
+      connectErrShown = true;
+    }
+  });
+
+  socket.on("new-item", (item) => {
+    if (item.channel !== channel) return;
+
+    if (item.type === "file") {
+      process.stdout.write(`📎 File: ${url}/uploads/${item.filename}\n`);
+      return;
+    }
+
+    if (item.type === "text") {
+      if (outputMode) {
+        process.stdout.write(item.content + "\n");
+      } else {
+        copyToClipboard(item.content);
+        process.stdout.write(`✓ Copied: "${truncate(item.content, 60)}"\n`);
+      }
+    }
+  });
+
+  process.on("SIGINT", () => {
+    stopping = true;
+    socket.disconnect();
+    process.stdout.write("\nStopped watching.\n");
+    process.exit(0);
+  });
+}
+
+run();

package/bin/instbyte.js

@@ -3,35 +3,90 @@
 "use strict";
 
 const path = require("path");
-const fs = require("fs");
+const fs   = require("fs");
+
+const args = process.argv.slice(2);
+const subcommand = args[0];
+
+const SUBCOMMANDS = ["send", "watch", "status"];
 
 // ========================
-// DATA DIRECTORY SETUP
+// HELP
 // ========================
-// When run via npx or global install, we want data to live
-// in the user's current working directory, not inside the
-// npm cache or global node_modules.
-//
-// When run via Docker, INSTBYTE_DATA and INSTBYTE_UPLOADS may
-// already be set via environment variables — respect those and
-// don't override them.
-
-if (!process.env.INSTBYTE_DATA) {
-    process.env.INSTBYTE_DATA = path.join(process.cwd(), "instbyte-data");
+function showHelp() {
+  console.log(`
+Usage:
+  instbyte                         Start the server
+  instbyte send <file|text>        Send a file or text to a channel
+  instbyte send                    Read from stdin and send
+  instbyte watch                   Watch a channel, copy new text to clipboard
+  instbyte status                  Check if a server is running
+
+Options (send / watch / status):
+  --server <url>                   Server URL  (overrides auto-discovery)
+  --channel <name>                 Target channel  (default: general)
+  --passphrase <pass>              Passphrase if auth is enabled
+  --uploader <name>                Display name for sent items  (default: OS username)
+  --output                         watch: print to stdout instead of clipboard
+  --quiet                          send: suppress confirmation output
+
+Examples:
+  instbyte send ./build.zip --channel assets
+  instbyte send "http://staging.myapp.com"
+  git log --oneline -20 | instbyte send
+  instbyte watch --channel projects
+  instbyte watch --output | grep error
+  instbyte status --server http://192.168.1.10:3000
+`);
 }
 
-if (!process.env.INSTBYTE_UPLOADS) {
-    process.env.INSTBYTE_UPLOADS = path.join(process.env.INSTBYTE_DATA, "uploads");
+// ========================
+// ROUTE
+// ========================
+if (args.includes("--help") || args.includes("-h")) {
+  if (!SUBCOMMANDS.includes(subcommand)) {
+    showHelp();
+    process.exit(0);
+  }
 }
 
-const dataDir = process.env.INSTBYTE_DATA;
-const uploadsDir = process.env.INSTBYTE_UPLOADS;
+if (SUBCOMMANDS.includes(subcommand)) {
+  // Each command module is loaded only when needed
+  const mod = path.join(__dirname, "cli", subcommand + ".js");
+  if (!fs.existsSync(mod)) {
+    console.error(`${subcommand}: not implemented yet`);
+    process.exit(1);
+  }
+  require(mod);
 
-if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true });
-if (!fs.existsSync(uploadsDir)) fs.mkdirSync(uploadsDir, { recursive: true });
+} else if (subcommand && !subcommand.startsWith("-")) {
+  console.error(`Unknown command: ${subcommand}`);
+  showHelp();
+  process.exit(1);
+
+} else {
+  // No subcommand (or only flags) — start the server
+  startServer();
+}
 
 // ========================
-// BOOT
+// SERVER START
 // ========================
-process.env.INSTBYTE_BOOT = '1';
-require("../server/server.js");
+function startServer() {
+  if (!process.env.INSTBYTE_DATA) {
+    process.env.INSTBYTE_DATA = path.join(process.cwd(), "instbyte-data");
+  }
+
+  if (!process.env.INSTBYTE_UPLOADS) {
+    process.env.INSTBYTE_UPLOADS = path.join(process.env.INSTBYTE_DATA, "uploads");
+  }
+
+  const dataDir    = process.env.INSTBYTE_DATA;
+  const uploadsDir = process.env.INSTBYTE_UPLOADS;
+
+  if (!fs.existsSync(dataDir))    fs.mkdirSync(dataDir,    { recursive: true });
+  if (!fs.existsSync(uploadsDir)) fs.mkdirSync(uploadsDir, { recursive: true });
+
+  process.env.INSTBYTE_BOOT = "1";
+  require("../server/server.js");
+}

package/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": {
@@ -45,6 +45,7 @@
     "multer": "^2.0.2",
     "sharp": "^0.33.2",
     "socket.io": "^4.6.1",
+    "socket.io-client": "^4.6.1",
     "sqlite3": "^5.1.6"
   },
   "devDependencies": {

package/server/server.js

@@ -855,7 +855,8 @@ app.get("/health", (req, res) => {
   res.json({
     status: "ok",
     uptime: Math.floor(process.uptime()),
-    version: require("../package.json").version
+    version: require("../package.json").version,
+    connected: connectedUsers
   });
 });
 
@@ -1092,6 +1093,23 @@ function listenOnFreePort(server, preferredPort) {
   });
 }
 
+function writeRuntimeConfig(ip, port) {
+  const dataDir = process.env.INSTBYTE_DATA;
+  if (!dataDir) return;
+
+  const runtimePath = path.join(dataDir, ".runtime.json");
+  const payload = JSON.stringify({
+    url: `http://${ip}:${port}`,
+    passphrase: config.auth.passphrase
+  }, null, 2);
+
+  try {
+    fs.writeFileSync(runtimePath, payload, "utf-8");
+  } catch (e) {
+    console.warn("Warning: could not write CLI runtime config:", e.message);
+  }
+}
+
 const PREFERRED = parseInt(process.env.PORT) || config.server.port;
 
 const localIP = getLocalIP();
@@ -1109,6 +1127,7 @@ if (process.env.INSTBYTE_BOOT === '1') {
     }
 
     console.log("");
+    writeRuntimeConfig(localIP, PORT);
     scanOrphans();
   }).catch(err => {
     console.error("Failed to start server:", err.message);