beam-term 📡

Zero-config local Wi-Fi & QR code P2P file, text, and clipboard beam utility across terminal, mobile phones, tablets, and desktop browsers.

Instantly transfer tokens, URLs, snippets, or files from your terminal or remote SSH sessions directly to your phone by scanning a rendered terminal QR code. No apps, no accounts, no external clouds.

✨ Features

• 📱 Zero Mobile App Required: Point your phone camera at your terminal screen to scan the QR code and instantly download the file or copy text to clipboard.
• 🚀 Zero-Config LAN Discovery: Automatically senses your local network interface (192.168.x.x, 10.x.x.x) and binds to an ephemeral HTTP server.
• ⚡ Powered by qr-term: Renders sharp inline QR codes directly in your shell (PowerShell, Bash, Zsh, macOS Terminal, iTerm2, Kitty).
• 🔒 PIN Authentication: Optional 4-digit PIN protection (--pin 1234) to prevent unauthorized LAN access.
• 📥 Two-Way Receive Mode: Start beamx --receive to drop files/photos from your phone directly into your current terminal directory.
• 🛡️ Auto-Termination (--once): Shuts down the temporary HTTP server as soon as the file or text has been retrieved.

🚀 Installation

Global CLI Tool

npm install -g beam-term
# or run directly with npx
npx beam-term myfile.pdf
# or using short alias
npx beamx "https://example.com"

In Your Project (Library)

npm install beam-term

🛠️ CLI Usage & Examples

1. Beam a File to Mobile / Browser

beamx archive.zip

2. Beam Clipboard Text / Auth Token

# Direct argument
beamx "https://staging-auth.corp/pair?token=88319"

# Or piped from clipboard / command
echo "2FA-SECRET-KEY-1234" | beamx

3. Receive Files from Phone into Terminal Directory

beamx --receive

Your phone opens an upload dropzone to beam photos or files straight into your computer.

4. Require PIN Authentication

beamx secret-report.pdf --pin 8492

📖 Programmatic API (TypeScript & JavaScript)

import { beam, BeamServer } from "beam-term";

// 1. Start Beam Server and Render Terminal QR Code
const instance = await beam("https://auth.company.com/pair", {
  once: true,
  pin: "1234",
});

console.log("Serving at:", instance.url);

// 2. Programmatic Server Control
const server = new BeamServer({
  mode: "send-file",
  filePath: "./build.tar.gz",
  fileName: "build.tar.gz",
});

await server.start();
server.on("complete", () => {
  console.log("File downloaded by mobile peer!");
});

⚙️ CLI Options Reference

| Option | Shorthand | Default | Description | | :--- | :--- | :--- | :--- | | --port <port> | -p | random | HTTP server port | | --host <host> | | auto | Network host/IP to advertise | | --pin <pin> | | none | Require 4-digit PIN for access | | --no-once | | false | Keep server running after first transfer | | --receive | -r | false | Start upload dropzone to receive files from phone | | --output <dir> | -o | . | Directory to save received files |

🧪 Development & Testing

git clone https://github.com/authoritydmc/beam-term.git
cd beam-term
npm install
npm test
npm run build

🚀 Automated Release & Versioning

1-Click from GitHub Actions

Go to Actions -> Automated Version & Release -> Select patch, minor, or major -> Click Run workflow.

From Terminal

npm run release:patch
npm run release:minor
npm run release:major

📄 License

MIT © 2026 authoritydmc