diff --git a/package.json b/package.json
index 355c907..e9e9e41 100644
--- a/package.json
+++ b/package.json
@@ -8,7 +8,10 @@
     "build": "vite build",
     "preview": "vite preview",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "cli": "bun run src/cli/qr-terminal.ts",
+    "cli:file": "bun run src/cli/qr-terminal.ts",
+    "build:cli": "esbuild src/cli/qr-terminal.ts --bundle --platform=node --target=node18 --outfile=dist/qr-terminal.js --format=esm --external:node:*"
   },
   "devDependencies": {
     "@preact/preset-vite": "2",
diff --git a/src/cli/qr-terminal.ts b/src/cli/qr-terminal.ts
new file mode 100644
index 0000000..6d6caf6
--- /dev/null
+++ b/src/cli/qr-terminal.ts
@@ -0,0 +1,169 @@
+#!/usr/bin/env bun
+/**
+ * QR Terminal Display
+ *
+ * Displays a sequence of QR codes in the terminal for text/file transfer.
+ * Reads text from stdin or a file argument, encodes it using the same
+ * protocol as the webapp, and loops through the QR sequence until
+ * interrupted.
+ *
+ * Usage:
+ *   bun run src/cli/qr-terminal.ts                    # read from stdin
+ *   bun run src/cli/qr-terminal.ts /path/to/file.txt  # read from file
+ *   node --import=tsx src/cli/qr-terminal.ts ...      # with tsx
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { generateQRMatrix } from '../core/qr/qr_encode';
+import { packetize } from '../core/sender/packetizer';
+import { scheduleFrames } from '../core/sender/scheduler';
+import { QR_VERSION, ECC_LEVEL } from '../core/protocol/constants';
+import { parseHeader } from '../core/protocol/packet';
+import { clearScreen, hideCursor, showCursor, renderToTerminal } from './terminal_raster';
+
+const FPS_MS = 100;
+
+// ────────────────────────────────────────────────────────────────────────
+// Argument parsing
+// ────────────────────────────────────────────────────────────────────────
+
+function readInput(): Uint8Array {
+  const args = process.argv.slice(2);
+
+  if (args.length > 0) {
+    const filePath = args[0]!;
+    if (!existsSync(filePath)) {
+      console.error(`Error: file not found: ${filePath}`);
+      process.exit(1);
+    }
+    return new Uint8Array(readFileSync(filePath));
+  }
+
+  // Read from stdin (fd 0)
+  try {
+    return new Uint8Array(readFileSync(0));
+  } catch (err: any) {
+    console.error(`Error reading stdin: ${err.message ?? String(err)}`);
+    process.exit(1);
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Encode pipeline (reuse webapp protocol)
+// ────────────────────────────────────────────────────────────────────────
+
+function buildFrames(data: Uint8Array): { packets: Uint8Array[]; genIndices: number[]; meta: { isText: boolean; isCompressed: boolean; totalGenerations: number; dataLength: number } } {
+  const result = packetize(data, false, true);
+  const ordered = scheduleFrames(result.packets, result.totalGenerations);
+  const genIndices = ordered.map((pkt) => parseHeader(pkt).generationIndex);
+
+  return {
+    packets: ordered,
+    genIndices,
+    meta: {
+      isText: result.isText,
+      isCompressed: result.isCompressed,
+      totalGenerations: result.totalGenerations,
+      dataLength: result.dataLength,
+    },
+  };
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Main loop
+// ────────────────────────────────────────────────────────────────────────
+
+function main() {
+  let data: Uint8Array;
+  try {
+    data = readInput();
+  } catch (err: any) {
+    console.error(`Error reading input: ${err.message ?? String(err)}`);
+    process.exit(1);
+  }
+
+  if (data.length === 0) {
+    console.error('Error: no input data. Provide a file path or pipe text to stdin.');
+    process.exit(1);
+  }
+
+  const { packets, genIndices, meta } = buildFrames(data);
+
+  // Pre-render all QR matrices to terminal strings
+  const frames: string[][] = [];
+  for (const pkt of packets) {
+    const matrix = generateQRMatrix(pkt, QR_VERSION, ECC_LEVEL);
+    frames.push(renderToTerminal(matrix));
+  }
+
+  const termWidth = process.stdout.columns ?? 80;
+  const termHeight = process.stdout.rows ?? 24;
+  const qrWidth = frames[0]?.[0]?.length ?? 0;
+  const qrHeight = frames[0]?.length ?? 0;
+  const padLeft = Math.max(0, Math.floor((termWidth - qrWidth) / 2));
+  const padTop = Math.max(0, Math.floor((termHeight - qrHeight - 4) / 2));
+
+  let running = true;
+  let frameIdx = 0;
+
+  function draw() {
+    if (!running) return;
+
+    const lines: string[] = [];
+
+    // Top padding
+    for (let i = 0; i < padTop; i++) {
+      lines.push('');
+    }
+
+    // QR frame, centered
+    for (const row of frames[frameIdx]!) {
+      lines.push(' '.repeat(padLeft) + row);
+    }
+
+    // Status lines
+    lines.push('');
+    lines.push(
+      ' '.repeat(padLeft) +
+        `Frame ${frameIdx + 1}/${frames.length}  |  Gen ${genIndices[frameIdx]! + 1}/${meta.totalGenerations}  |  ` +
+        `${meta.isText ? 'text' : 'binary'} ${meta.isCompressed ? '(compressed)' : ''}`,
+    );
+    lines.push(' '.repeat(padLeft) + `Press q or Ctrl-C to quit`);
+
+    clearScreen();
+    process.stdout.write(lines.join('\n'));
+
+    frameIdx = (frameIdx + 1) % frames.length;
+  }
+
+  function cleanup() {
+    running = false;
+    clearInterval(interval);
+    clearScreen();
+    showCursor();
+    process.stdout.write('QR terminal display stopped.\n');
+    process.exit(0);
+  }
+
+  // Keyboard handling
+  if (process.stdin.isTTY) {
+    hideCursor();
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (key: string) => {
+      if (key === 'q' || key === 'Q' || key === '\u0003') {
+        cleanup();
+      }
+    });
+  }
+
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+
+  // Start loop
+  draw();
+  const interval = setInterval(draw, FPS_MS);
+}
+
+main();
diff --git a/src/cli/terminal_raster.ts b/src/cli/terminal_raster.ts
new file mode 100644
index 0000000..79ce48c
--- /dev/null
+++ b/src/cli/terminal_raster.ts
@@ -0,0 +1,65 @@
+/**
+ * Terminal QR rasterizer.
+ *
+ * Renders a QR-code boolean matrix into compact terminal output using
+ * half-block Unicode characters (U+2580 / U+2584 / U+2588 / space).
+ * Each terminal row displays two QR rows, giving an approximately
+ * square aspect ratio in typical monospace terminals.
+ */
+
+const BLOCK_FULL = '\u2588';
+const BLOCK_UPPER = '\u2580';
+const BLOCK_LOWER = '\u2584';
+const BLOCK_EMPTY = ' ';
+
+/**
+ * Render a QR boolean matrix to terminal lines.
+ * @param matrix 2-D array where true = dark module
+ * @returns Array of terminal strings (one per screen row)
+ */
+export function renderToTerminal(matrix: boolean[][]): string[] {
+  const size = matrix.length;
+  const lines: string[] = [];
+
+  for (let y = 0; y < size; y += 2) {
+    let line = '';
+    for (let x = 0; x < size; x++) {
+      const top = matrix[y][x];
+      const bottom = y + 1 < size ? matrix[y + 1][x] : false;
+
+      if (top && bottom) {
+        line += BLOCK_FULL;
+      } else if (top) {
+        line += BLOCK_UPPER;
+      } else if (bottom) {
+        line += BLOCK_LOWER;
+      } else {
+        line += BLOCK_EMPTY;
+      }
+    }
+    lines.push(line);
+  }
+
+  return lines;
+}
+
+/**
+ * Clear the terminal screen and move cursor to home position.
+ */
+export function clearScreen(): void {
+  process.stdout.write('\x1b[2J\x1b[H');
+}
+
+/**
+ * Hide the terminal cursor.
+ */
+export function hideCursor(): void {
+  process.stdout.write('\x1b[?25l');
+}
+
+/**
+ * Show the terminal cursor.
+ */
+export function showCursor(): void {
+  process.stdout.write('\x1b[?25h');
+}
diff --git a/src/tests/cli_rendering.test.ts b/src/tests/cli_rendering.test.ts
new file mode 100644
index 0000000..fce2448
--- /dev/null
+++ b/src/tests/cli_rendering.test.ts
@@ -0,0 +1,230 @@
+/**
+ * Tests for the CLI terminal QR rasterizer.
+ *
+ * Verifies that the terminal rasterizer correctly renders boolean QR matrices
+ * as half-block Unicode art, that the encoder pipeline produces valid QR data,
+ * and the end-to-end CLI pipeline works (without actually clearing the screen).
+ */
+import { describe, it, expect } from 'vitest';
+
+describe('Terminal Rasterizer', () => {
+  it('should render a simple 2×2 matrix', async () => {
+    const { renderToTerminal } = await import('@/cli/terminal_raster');
+
+    // 2×2 matrix: all dark
+    const matrix = [
+      [true, true],
+      [true, true],
+    ];
+
+    const lines = renderToTerminal(matrix);
+    // 2 rows → 1 terminal line (two QR rows per terminal row)
+    expect(lines.length).toBe(1);
+    // both QR rows dark → ██
+    expect(lines[0]).toBe('\u2588\u2588');
+  });
+
+  it('should render mixed 4×4 matrix', async () => {
+    const { renderToTerminal } = await import('@/cli/terminal_raster');
+
+    const matrix = [
+      [true, false, true, false],
+      [false, true, false, true],
+      [true, true, false, false],
+      [false, false, true, true],
+    ];
+
+    const lines = renderToTerminal(matrix);
+    expect(lines.length).toBe(2); // 4 QR rows → 2 terminal rows
+
+    // Row 0: top=TG, bottom=FB for each column
+    // Col 0: top=true, bottom=false → ▀ (U+2580)
+    expect(lines[0]![0]).toBe('\u2580');
+    // Col 1: top=false, bottom=true → ▄ (U+2584)
+    expect(lines[0]![1]).toBe('\u2584');
+    // Col 2: top=true, bottom=false → ▀
+    expect(lines[0]![2]).toBe('\u2580');
+    // Col 3: top=false, bottom=true → ▄
+    expect(lines[0]![3]).toBe('\u2584');
+
+    // Row 1: top=row2[TG], bottom=row3[FB]
+    // Col 0: top=true, bottom=false → ▀
+    expect(lines[1]![0]).toBe('\u2580');
+    // Col 1: top=true, bottom=false → ▀
+    expect(lines[1]![1]).toBe('\u2580');
+    // Col 2: top=false, bottom=true → ▄
+    expect(lines[1]![2]).toBe('\u2584');
+    // Col 3: top=false, bottom=true → ▄
+    expect(lines[1]![3]).toBe('\u2584');
+  });
+
+  it('should handle odd number of QR rows', async () => {
+    const { renderToTerminal } = await import('@/cli/terminal_raster');
+
+    // 3×3 matrix — odd number of rows
+    const matrix = [
+      [true, false, true],
+      [false, true, false],
+      [true, false, true],
+    ];
+
+    const lines = renderToTerminal(matrix);
+    expect(lines.length).toBe(2); // 3 QR rows → 2 terminal rows
+
+    // Row 0: QR rows 0+1
+    expect(lines[0]!.length).toBe(3);
+
+    // Row 1: QR row 2 + bottom=false (out of bounds)
+    expect(lines[1]!.length).toBe(3);
+    // Col 0: top=true, bottom=false → ▀
+    expect(lines[1]![0]).toBe('\u2580');
+    // Col 1: top=false, bottom=false → ' '
+    expect(lines[1]![1]).toBe(' ');
+    // Col 2: top=true, bottom=false → ▀
+    expect(lines[1]![2]).toBe('\u2580');
+  });
+
+  it('should render an all-white matrix', async () => {
+    const { renderToTerminal } = await import('@/cli/terminal_raster');
+
+    const matrix = [
+      [false, false],
+      [false, false],
+    ];
+
+    const lines = renderToTerminal(matrix);
+    expect(lines.length).toBe(1);
+    expect(lines[0]).toBe('  '); // space + space
+  });
+
+  it('should render a full-block matrix', async () => {
+    const { renderToTerminal } = await import('@/cli/terminal_raster');
+
+    const matrix = [
+      [true, true],
+      [true, true],
+    ];
+
+    const lines = renderToTerminal(matrix);
+    expect(lines.length).toBe(1);
+    expect(lines[0]).toBe('\u2588\u2588'); // full block + full block
+  });
+});
+
+describe('CLI Screen Helpers', () => {
+  it('should produce escape sequences', async () => {
+    const { clearScreen } = await import('@/cli/terminal_raster');
+    // Just check it writes to stdout without throwing
+    expect(typeof clearScreen).toBe('function');
+  });
+
+  it('should produce cursor visibility sequences', async () => {
+    const { hideCursor, showCursor } = await import('@/cli/terminal_raster');
+    expect(typeof hideCursor).toBe('function');
+    expect(typeof showCursor).toBe('function');
+  });
+});
+
+describe('CLI Encoder Pipeline', () => {
+  it('should produce the same frames as the web app (reuse common logic)', async () => {
+    const { packetize } = await import('@/core/sender/packetizer');
+    const { scheduleFrames } = await import('@/core/sender/scheduler');
+    const { generateQRMatrix } = await import('@/core/qr/qr_encode');
+    const { QR_VERSION, ECC_LEVEL } = await import('@/core/protocol/constants');
+    const { parseHeader } = await import('@/core/protocol/packet');
+
+    // Use >64 bytes so compression is actually triggered (packetizer skips small payloads)
+    const data = new TextEncoder().encode('CLI test payload for verifying protocol reuse. '.repeat(3));
+    const result = packetize(data, false, true);
+    const ordered = scheduleFrames(result.packets, result.totalGenerations);
+    const genIndices = ordered.map((pkt) => parseHeader(pkt).generationIndex);
+
+    // Same protocol as web app: frames with meta info
+    for (const pkt of ordered) {
+      const matrix = generateQRMatrix(pkt, QR_VERSION, ECC_LEVEL);
+      // Each matrix should be square (V10 = 57×57)
+      expect(matrix.length).toBe(57);
+      expect(matrix[0]!.length).toBe(57);
+    }
+
+    // All generation indices in range
+    expect(genIndices.every((g) => g >= 0 && g < result.totalGenerations)).toBe(true);
+    expect(result.isCompressed).toBe(true);
+    expect(result.dataLength).toBeGreaterThan(0);
+  });
+});
+
+describe('CLI Frame Cycle', () => {
+  it('should loop through frames deterministically', async () => {
+    const { packetize } = await import('@/core/sender/packetizer');
+    const { scheduleFrames } = await import('@/core/sender/scheduler');
+
+    const data = new TextEncoder().encode('Frame cycle test — small payload');
+    const result = packetize(data, false, false);
+    const ordered = scheduleFrames(result.packets, result.totalGenerations);
+
+    // Frame sequence should be consistent
+    expect(ordered.length).toBe(result.packets.length);
+
+    // Simulate looping: collect frame indices over 3 full cycles
+    const totalFrames = ordered.length;
+    const frameSequence: number[] = [];
+    for (let i = 0; i < totalFrames * 3; i++) {
+      frameSequence.push(i % totalFrames);
+    }
+
+    // Should see each frame multiple times
+    const uniqueIndices = new Set(frameSequence);
+    expect(uniqueIndices.size).toBe(totalFrames);
+    expect(frameSequence.length).toBe(totalFrames * 3);
+  });
+
+  it('should generate valid QR matrix for every scheduled frame', async () => {
+    const { packetize } = await import('@/core/sender/packetizer');
+    const { scheduleFrames } = await import('@/core/sender/scheduler');
+    const { generateQRMatrix } = await import('@/core/qr/qr_encode');
+    const { QR_VERSION, ECC_LEVEL } = await import('@/core/protocol/constants');
+
+    const data = new TextEncoder().encode('Every frame QR test — medium payload');
+    const result = packetize(data, false, true);
+    const ordered = scheduleFrames(result.packets, result.totalGenerations);
+
+    // Every packet should produce a valid QR matrix
+    for (const pkt of ordered) {
+      const matrix = generateQRMatrix(pkt, QR_VERSION, ECC_LEVEL);
+      expect(matrix.length).toBe(57);
+      expect(matrix[0]!.length).toBe(57);
+      // At least one dark module (QR codes always have finder patterns)
+      const hasDark = matrix.some((row) => row.some((cell) => cell));
+      expect(hasDark).toBe(true);
+    }
+  });
+});
+
+describe('CLI Input Parsing', () => {
+  it('should read file from argument and produce frames', async () => {
+    // This tests the buildFrames function logic directly
+    const { packetize } = await import('@/core/sender/packetizer');
+    const { scheduleFrames } = await import('@/core/sender/scheduler');
+    const { parseHeader } = await import('@/core/protocol/packet');
+
+    // Simulate reading a file
+    const fileData = new TextEncoder().encode('file content test');
+    const result = packetize(fileData, true, false);
+    const ordered = scheduleFrames(result.packets, result.totalGenerations);
+    const genIndices = ordered.map((pkt) => parseHeader(pkt).generationIndex);
+
+    expect(ordered.length).toBeGreaterThan(0);
+    expect(result.isText).toBe(true);
+    expect(result.isCompressed).toBe(false);
+    expect(result.dataLength).toBe(fileData.length);
+    expect(genIndices.length).toBe(ordered.length);
+  });
+
+  it('should handle empty input gracefully and provide error message', () => {
+    // The main function checks for empty data and exits with error
+    // We test the condition directly
+    const data = new Uint8Array(0);
+    expect(data.length).toBe(0);
+  });
+});
diff --git a/vite.config.ts b/vite.config.ts
index 041c88c..37c102c 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -20,7 +20,7 @@ export default defineConfig({
   worker: {
     format: 'es',
   },
-  base: '/hermes-web-demos/qr/',
+  base: '/hermes-web-demos/qr-transfer/',
   build: {
     outDir: 'dist',
     emptyOutDir: true,