CLI

The duckviz CLI is a small Node binary published on npm. It lets you load local files into your active browser session without clicking around in the upload UI.

Install

No install needed — use npx:

npx duckviz ./logs/ -r

Or install globally:

npm install -g duckviz
duckviz --help

Usage

duckviz <paths...> [options]

Options:
  -r, --recursive    Walk directories recursively
      --fresh        Replace the current session (instead of appending)
      --url <url>    Custom web app URL (default: https://app.duckviz.com)
  -h, --help         Show help

Examples

# Append a single file
npx duckviz data.csv

# Recursively push a folder of logs, replacing the current session
npx duckviz ./logs/ -r --fresh

# Point at a local dev server
npx duckviz . --url http://localhost:3001

How it works

1. The CLI walks your input paths, applies the extension allowlist, and builds a file manifest.
2. It starts an ephemeral HTTP server on 127.0.0.1:<random-port> and mints a one-shot bearer token.
3. Your default browser opens app.duckviz.com/cli-receive?endpoint=...&token=.... The page immediately scrubs the token from the URL bar.
4. The browser authenticates to the local server with the token, downloads each manifest file, and hands them to the global store.
5. You land on /directory, ingestion starts, and the CLI's server shuts down.

Nothing is uploaded to the internet — the transfer is browser ↔ localhost.

Security guarantees

The local server enforces:

• Bearer-only auth (no ?token= query fallback — never leaks via logs/Referer).
• DNS rebinding guard — the Host header must match the bound loopback port.
• Path-traversal guard — only manifest-registered relative paths are served.
• Manifest-gated --fresh — a crafted ?mode=fresh link cannot wipe state until the CLI's token has been accepted.
• Idle timeout — the server auto-shuts down after 10 minutes if the browser never returns.