CLI Reference nfltr

Reference for nfltr.xyz users. Use this page for client-side nfltr commands that connect to the hosted relay: secure tunnels, sharing, orchestration observability, and fleet operations from your workstation.

New to NFLTR? Start with When to Use NFLTR, then return here for command-level detail.

Start From The Right Command Path

After you choose a path, use the sections below as the deep command reference for flags, environment variables, examples, and operational details.

Installation

Download the binary for your platform from the landing page:

# Example: macOS Apple Silicon
chmod +x nfltr-darwin-arm64
sudo mv nfltr-darwin-arm64 /usr/local/bin/nfltr

Commands

nfltr http — HTTP Tunnel

Expose a local HTTP service through an encrypted tunnel.

nfltr http [port|url] [flags]

Arguments

If omitted, defaults to http://localhost:8080.

Flags

Access control flags

These flags protect different layers and can be combined:

--basic-auth and --share-auth are not redundant. --basic-auth runs on your machine and gates all incoming requests. --share-auth is sent to the server as a policy and only applies to the public share URL. Use both together to protect the browse URL with one password and the share URL with another.

Examples

# Basic — expose port 8080
nfltr http 8080

# Custom name — access at /browse/myapp/
nfltr http 3000 --name myapp

# Public share URL is included by default; disable with --no-share
nfltr http 8080 --no-share

# Multi-backend routing (route /api to port 3000, default to 8080)
nfltr http 8080 --route /api=3000

# Multiple backends
nfltr http 8080 --route /api=3000 --route /ws=4000

# Expose an HTTPS local service
nfltr http https://localhost:3443

# Verbose logging of all proxied requests
nfltr http 8080 --verbose

# Limited duration (auto-stop after 1 hour)
nfltr http 8080 --duration 3600

Connection banner

nfltr                  vX.Y.Z
Agent ID               myapp
Forwarding             https://nfltr.xyz/browse/myapp/ → http://localhost:8080

2026/03/25 10:20:55 Resolved identity: myapp
2026/03/25 10:20:55 Share URL: https://vivid-hawk.nfltr.xyz/
2026/03/25 10:20:55 Connected — waiting for requests... (press Ctrl+C to stop)

With --verbose, every proxied request is also logged:

[1] GET  /              → 200 (4521 bytes, 12ms)
[2] GET  /style.css     → 200 (1200 bytes, 3ms)

nfltr tcp — TCP Tunnel (Agent Side)

Expose a local TCP port (SSH, databases, Redis, etc.) through an encrypted gRPC tunnel. Run this on the machine that hosts the service.

nfltr tcp <port> [flags]

Flags

Examples

# Expose SSH
nfltr tcp 22 --name my-ssh

# Expose PostgreSQL
nfltr tcp 5432 --name my-db

# Expose Redis
nfltr tcp 6379 --name my-redis

Connection banner

nfltr vX.Y.Z starting TCP tunnel
  agent-id:  my-ssh
  server:    grpc.nfltr.xyz:443 (tls=true)
  tunnel:    TCP → localhost:22
Connected — TCP tunnel active for localhost:22

  Connect from another machine:
    nfltr tcp-connect my-ssh 22 --listen :<local-port> --server nfltr.xyz:443

  SSH example (if tunneling port 22):
    nfltr tcp-connect my-ssh 22 --listen :2222 --server nfltr.xyz:443
    ssh -p 2222 user@localhost

nfltr tcp-connect — TCP Client (Connect Side)

Connect to a remote agent's TCP service by creating a local TCP listener that tunnels connections through the server. Works with any TCP client (ssh, psql, redis-cli, mysql, etc.).

nfltr tcp-connect <agent-name> <port> [flags]

Arguments

Flags

Examples

# SSH to a remote machine
nfltr tcp-connect my-ssh 22 --listen :2222
ssh -p 2222 user@localhost

# Connect to a remote PostgreSQL
nfltr tcp-connect my-db 5432 --listen :5432
psql -h localhost -p 5432 mydb

# Redis — use random port (shown in banner)
nfltr tcp-connect my-redis 6379
redis-cli -p 54321

# MySQL
nfltr tcp-connect my-mysql 3306 --listen :3306
mysql -h 127.0.0.1 -P 3306 -u root

Connection flow

Your machine                  nfltr Server               Remote Agent
────────────                  ────────────               ────────────
ssh -p 2222 localhost
  │
tcp-connect listener ─HTTP /connect/my-ssh/22─────────→ TCPDispatcher
                                                          bridges gRPC
                              ←──gRPC ConnectTCP stream──── nfltr tcp 22
                                                                dials localhost:22
←─────────────────────────────────bidirectional bytes──────────────────────→

Comparison: server-configured vs tcp-connect

Prerequisite: The server must have tcp.enabled=true. The /connect/{agent_id}/{port} endpoint is available automatically.

SSH config shortcut

# ~/.ssh/config
Host my-ssh
  ProxyCommand nfltr ssh-proxy --name %h --port %p
  User admin

nfltr grpc — gRPC Tunnel new

Expose a local gRPC service through a TCP tunnel so it can be reached remotely via grpcurl, Postman gRPC, BloomRPC, or any gRPC client. Uses TCP tunneling (not HTTP proxy) to preserve HTTP/2 framing, trailers, and bidirectional streaming.

nfltr grpc <port> [flags]

Flags

Examples

# Expose local gRPC service
nfltr grpc 50051

# With custom name
nfltr grpc 50051 --name my-grpc-api

# Connect from another machine
nfltr tcp-connect <agent>.my-grpc-api 50051 --listen :50051 --server nfltr.xyz:443
grpcurl -plaintext localhost:50051 list

Connection banner

nfltr vX.Y.Z — gRPC tunnel to localhost:50051
  agent-id:  alice.my-grpc-api
  server:    grpc.nfltr.xyz:443 (tls=true)
  tunnel:    TCP → localhost:50051 (gRPC/HTTP2)
Connected — gRPC tunnel active for localhost:50051

  Connect from another machine:
    nfltr tcp-connect alice.my-grpc-api 50051 --listen :50051 --server nfltr.xyz:443

  Then test with grpcurl:
    grpcurl -plaintext localhost:50051 list
    grpcurl -plaintext localhost:50051 <service>/<method>

Why TCP tunneling?

gRPC requires HTTP/2 end-to-end — framing, trailers, and bidirectional streaming. The HTTP proxy path decomposes requests into protobuf envelopes, which breaks these semantics. TCP tunneling forwards raw bytes and preserves the protocol correctly.

Connection flow

Your machine                  nfltr Server               Remote Machine
┌────────────────                  ┌────────────               ┌────────────
grpcurl localhost:50051
  │
tcp-connect listener →HTTP /connect/agent/50051→ TCPDispatcher
                                                          bridges gRPC
                              ←──gRPC ConnectTCP stream──── nfltr grpc 50051
                                                                dials localhost:50051
←───────────────────────────────bidirectional gRPC bytes──────────────────→

nfltr command — Expose a CLI Command as an HTTP Endpoint new

Turn any CLI tool into an HTTP microservice, tunnelled through the server. POST requests pipe the body as stdin (or as a flag argument) to the command and return stdout as the response. GET / serves a chat-style web UI with markdown rendering.

nfltr command <cmd> [args...] [flags]

Flags

Examples

# Echo service (stdin → stdout)
nfltr command cat

# JSON formatter as a service
nfltr command jq .

# Python script (share URL included automatically)
nfltr command python3 myscript.py

# Shell pipeline
nfltr command sh -c "sort | uniq"

# GitHub Copilot CLI as a remote AI assistant:
nfltr command --name copilot --basic-auth 'admin:pass' \
  --body-as-arg -p --timeout 600 --model claude-sonnet-4 \
  --cwd /path/to/project \
  copilot -- --allow-all-tools

# Run on multiple repos (one instance per repo):
nfltr command --name copilot-frontend --body-as-arg -p \
  --cwd ~/projects/frontend copilot -- --allow-all-tools
nfltr command --name copilot-backend --body-as-arg -p \
  --cwd ~/projects/backend copilot -- --allow-all-tools

Web UI features

• Chat-style interface with user/assistant message bubbles
• Markdown rendering with syntax-highlighted code blocks
• Model selector dropdown (sends X-Model header per request)
• File attachment support
• Typing indicator during command execution
• Basic auth with session cookies (24h TTL)

How --body-as-arg works

Without it, the POST body is piped as stdin to the command. With --body-as-arg -p, the body is appended as a flag argument instead:

This is essential for tools like GitHub Copilot CLI that read input from a flag (-p) rather than stdin.

nfltr tail — Live File Streaming new

Stream the tail of any file via a public URL — like tail -f over the internet. Visitors see live updates via Server-Sent Events in a web UI with search, pause, and auto-scroll.

nfltr tail [flags] <file>

Flags

Endpoints served

Examples

# Stream syslog with a share URL
nfltr tail /var/log/syslog

# Show last 200 lines
nfltr tail --lines 200 /var/log/nginx/access.log

# Password-protected log stream
nfltr tail --basic-auth admin:secret app.log

# Named agent for easy identification
nfltr tail --name prod-logs /var/log/app.log

# Plain-text access from another machine
curl https://<share-url>/raw

nfltr terminal — Web-Based Terminal new

Open a browser-accessible xterm.js terminal on the agent machine, tunnelled through the server via HTTP polling. Works through any HTTP proxy — no WebSocket support required.

nfltr terminal [flags]

Flags

One of --basic-auth or --no-auth is required.

Examples

# Password-protected web terminal
nfltr terminal --basic-auth admin:secret

# Custom shell
nfltr terminal --shell /bin/zsh --basic-auth user:pass

# Named agent with share URL
nfltr terminal --name my-box --share --basic-auth admin:secret

# No auth (testing only)
nfltr terminal --no-auth

How it works

Browser (xterm.js)           nfltr.xyz             Agent machine
  ┌─ POST /input ───────────└── HTTP tunnel ──────└───────────────────────└
  │                      │                    │  nfltr terminal       │
  │─ GET  /output ──────────│────────────────────│  PTY └───┌ shell      │
  ┌─ GET  /resize ──────────├                    ├───────────────────────├
  ├───────────────────────├

Allocates a real PTY and starts a shell. HTTP polling at 50ms intervals delivers keystrokes and output — fully interactive, works through corporate proxies and firewalls.

nfltr shell vs nfltr terminal — which should I use?

Both give you remote shell access through a tunnel, but they work in fundamentally different ways:

Rule of thumb: Use nfltr terminal when you want a one-click browser shell with a shareable URL. Use nfltr shell when you need SCP, SFTP, port forwarding, or want to use your existing SSH client and config.

nfltr a2a — Agent-to-Agent Communication new

Direct messaging between agents through the relay server. Supports unary send/receive, persistent listening, and bidirectional streaming. In multi-pod deployments, messages are routed across pods automatically.

nfltr a2a <command> [flags]

Sub-commands

Flags

Examples

# Send a message to another agent
nfltr a2a send sensor-42 "get status"

# Pipe JSON through stdin
echo '{"cmd":"status"}' | nfltr a2a send sensor-42

# Listen for incoming messages
nfltr a2a listen --name responder

# Bidirectional pipe (interactive)
nfltr a2a pipe sensor-42

# Pipe a file through another agent
cat data.json | nfltr a2a pipe processor-agent > result.json

Use cases

• IoT sensor data collection (send + listen)
• Remote command execution between agents
• File transfer between machines behind NAT
• Interactive chat between two agents

nfltr p2p — Peer-to-Peer Direct Transfer new

Transfer files, chat, and audio/video calls directly between two machines. The server is used only for initial signaling — all data flows over a direct TCP connection between peers, authenticated with HMAC-SHA256 and encrypted with AES-256-CTR. This means lower latency, no server bandwidth costs, and true end-to-end encryption.

nfltr p2p <command> [flags]

Sub-commands

Shared flags

recv-specific flags

Examples

# ── File transfer (complementary pair) ──────────────
# Terminal 1: receiver waits for incoming files
nfltr p2p recv --name bob-laptop --output ~/received/

# Terminal 2: sender transfers a file
nfltr p2p send report.pdf bob-laptop

# Use the exact scoped peer ID when targeting another API key scope
nfltr p2p send report.pdf partner-key.bob-laptop

# ── Directory transfer ──────────────────────────────
nfltr p2p send ./project/ bob-laptop

# ── Restrict who can send to you ────────────────────
nfltr p2p recv --name bob-laptop --from alice-desktop

# ── Keep receiving multiple transfers ───────────────
nfltr p2p recv --name bob-laptop --keep

# ── Encrypted chat (both sides) ─────────────────────
# Terminal 1:
nfltr p2p chat bob-laptop --name alice-desktop

# Terminal 2:
nfltr p2p chat alice-desktop --name bob-laptop

# ── Audio/video call (both sides) ─────────────────
# Terminal 1 (caller):
nfltr p2p call bob-laptop --name alice-desktop

# Terminal 2 (receiver should already be listening):
nfltr p2p recv --name bob-laptop

# Headless mode (print URL instead of auto-open):
nfltr p2p call bob-laptop --name alice-desktop --no-browser
nfltr p2p recv --name bob-laptop --no-browser

Peer ID resolution: nfltr p2p list shows the peers visible to the current API key. If a peer appears as partner-key.bob-laptop, use that exact ID in send, chat, or call. A bare alias like bob-laptop only resolves when it is unique in that visible list.

How it works

1. Signaling — Both peers connect to the server via gRPC. The initiator sends an offer with a session token and candidate addresses; the responder replies with an answer.
2. Candidate gathering — Each peer discovers its local LAN IPs and queries a STUN server for its public (NAT-reflexive) address.
3. Direct connection — All candidates are dialed in parallel. The first working TCP path wins (LAN-direct, STUN-reflexive, or hairpin NAT).
4. HMAC authentication — A mutual HMAC-SHA256 challenge-response verifies both peers hold the same session token. Replay attacks are prevented by binding the HMAC to a unique session ID.
5. Encrypted transport — After authentication, both sides derive a shared AES-256 key and per-direction IVs from the token and challenges. All subsequent data is encrypted with AES-256-CTR — the connection is fully end-to-end encrypted.
6. Data transfer — Files, directories, chat messages, or call signaling/media flow over the encrypted direct TCP connection. The server is no longer involved.

A2A vs P2P — when to use which

A2A and P2P have similar-sounding subcommands but are not interchangeable — they solve fundamentally different problems:

Why similar names? Both have a "send" side and a "receive" side, but the similarity ends there. a2a send sends a text message through the server; p2p send transfers a file over a direct TCP connection. a2a pipe is like netcat through gRPC; p2p chat is an interactive terminal UI over a direct link. You cannot send files with A2A (no metadata, no checksums), and you cannot send arbitrary text messages with P2P send (it requires a file path).

nfltr shell — Embedded SSH Server new

Starts an embedded SSH server on the agent machine and exposes it through the TCP tunnel — no OpenSSH or sshd required. Remote users can access a shell via the browser terminal in the dashboard or through any SSH client. See shell vs terminal comparison to decide which to use.

nfltr shell [flags]

Authentication modes

At least one of --password, --authorized-keys, or --no-auth is required.

Flags

Examples

# Password auth
nfltr shell --password secret

# Public key auth
nfltr shell --authorized-keys ~/.ssh/authorized_keys

# No auth (smoke tests only)
nfltr shell --no-auth

Connecting

Once the shell agent is running, there are three ways to connect:

1. Browser terminal (dashboard) — click the ► Term button on the agent card in the dashboard. Requires http.terminal.enabled=true on the server (enabled by default on nfltr.xyz).

2. TCP connect + SSH

nfltr tcp-connect <agent-id> 22 --listen :2222
ssh -p 2222 user@localhost

3. SSH proxy

ssh -o ProxyCommand="nfltr ssh-proxy --name <agent-id> --port 22" user@agent

How it works

┌────────────┐  TCP tunnel  ┌─────────────┐  ConnectTCP  ┌────────────────────┐
│ SSH Client │─────────────→│  rpc-server │─────────────→│  nfltr shell       │
│ or Browser │              │             │              │  (embedded sshd)   │
└────────────┘              └─────────────┘              └────────────────────┘

The embedded SSH server listens on a random local port. The TCP tunnel forwards connections from the server to that port. No system-level SSH daemon is needed.

nfltr ssh-proxy — SSH ProxyCommand Helper

Acts as an SSH ProxyCommand that tunnels SSH sessions through the server's HTTP /connect/{agent_id}/{port} endpoint.

nfltr ssh-proxy --name <agent> [--port <port>] [flags]

Flags

SSH config example

# ~/.ssh/config
Host mydevice
    ProxyCommand nfltr ssh-proxy --name %h --port %p
    User admin

Then simply:

ssh mydevice          # connects through the nfltr tunnel
scp file mydevice:/path
sftp mydevice

Inline usage

ssh -o ProxyCommand="nfltr ssh-proxy --name myagent --port %p" user@myagent

nfltr status — Server Status

Check server connectivity and list connected agents.

nfltr status [flags]

Flags

Example output

nfltr dev

Server:  grpc.nfltr.xyz:443
URL:     https://nfltr.xyz
Status:  online
Latency: 668ms

nfltr diagnose — Connectivity Diagnostics

Run a comprehensive connectivity test against your configured NFLTR endpoints.

nfltr diagnose [flags]

Tests (in order):

1. DNS Resolution — resolves the server hostname
2. HTTP Connectivity — GET to the server's HTTPS endpoint
3. HTTPS/TLS — validates the TLS certificate chain
4. gRPC Port — TCP dial to the gRPC port
5. TLS Handshake — verifies TLS works on the gRPC port
6. Round-trip Latency — measures end-to-end HTTPS latency

Example output

nfltr dev — connection diagnostics

DNS resolution (grpc.nfltr.xyz)         OK    34.61.152.169
DNS resolution (nfltr.xyz)              OK    104.21.16.130, 172.67.212.183
TCP connection (grpc.nfltr.xyz:443)     OK    254ms
TLS handshake (grpc.nfltr.xyz:443)      OK    1.511s (TLS 1.3)
HTTP endpoint (https://nfltr.xyz)       OK    200 (622ms)
gRPC channel (grpc.nfltr.xyz:443)       OK    3ms

6/6 tests passed
All connectivity tests passed.

nfltr config — Configuration Management

Manage the nfltr configuration file (stored at ~/.config/nfltr/nfltr.json).

nfltr config <command>

Sub-commands

Examples

# Save your API key (stored as "default")
nfltr config add-api-key rpc_abc123...

# Save a friend's key with a label
nfltr config add-api-key rpc_xyz789... --name alice

# List all saved keys (* marks the active key)
nfltr config list-api-keys
# * default      rpc_...c123
#   alice        rpc_...z789

# Switch active key
nfltr config use-api-key alice

# Remove a key
nfltr config remove-api-key alice

# Check current config
nfltr config check

# Find config file
nfltr config path
# → /Users/you/.config/nfltr/nfltr.json

Per-command key selection

All commands accept --key-name <label> to use a specific named key without switching the global active key:

nfltr a2a send bob-laptop hello --key-name alice
nfltr http 8080 --key-name work
nfltr p2p chat bob-laptop --key-name bob

Priority chain: --api-key flag → NFLTR_API_KEY env → --key-name lookup → active key from config.

Config file format

{
  "api_key": "rpc_abc123...",
  "api_keys": {
    "default": "rpc_abc123...",
    "alice": "rpc_xyz789..."
  },
  "server": "grpc.nfltr.xyz:443",
  "name": "my-laptop"
}

Override with environment variable: NFLTR_CONFIG=/path/to/config.json

nfltr orch — Hosted Orchestration CLI

Client-side orchestration against the nfltr.xyz control plane. The CLI is grouped by operator intent: start work, inspect tasks, manage workers, handle HITL queues, and maintain local orchestration state.

nfltr orch <group> <command> [flags]

Command groups

Shared orch flags

Most orch subcommands accept connection flags: --server, --proxy-url, --api-key, --json, --task-store-file, --quiet, --silent, --no-derive-proxy, and --agent-id.

start

Start one-off work, a planner-authored spec, a worker task, a batch manifest, or a graph run.

nfltr orch start goal "fix the failing auth tests" [--worktree] [--watch]
nfltr orch start spec ./objective.json [--worktree] [--watch] [--json]
nfltr orch start worker --worker WORKER_ID --role implementer --objective "..." [flags]
nfltr orch start batch ./batch.json [--batch-id ID] [--watch]
nfltr orch start graph run --manifest graph.json [flags]

Flags

# Dispatch one worker task and watch to completion
nfltr orch start worker --worker impl-pool-1 --role implementer \
  --objective "Regenerate docs" --watch --retry-on-transient 3

# Run a phased spec from stdin
nfltr orch spec decompose --goal "Ship docs and tests" | nfltr orch start spec - --watch

# Dry-run payload inspection for a worker task
nfltr orch start worker --worker impl-pool-1 --role implementer \
  --objective "..." --dry-run --json

task

List tasks from the local task store. Repeat --filter key=value for AND semantics (e.g. --filter role=implementer, --filter batch_id=iter-78).

nfltr orch task list [--active] [--filter key=value]... [flags]
nfltr orch task status --task TASK_ID [--events N] [--json]
nfltr orch task events --task TASK_ID [--tail N] [--since SEQUENCE] [--json]
nfltr orch task watch --task TASK_ID [--json]
nfltr orch task wait --task TASK_ID
nfltr orch task result --task TASK_ID
nfltr orch task diff --task TASK_ID
nfltr orch task cancel --task TASK_ID --reason "stuck past SLA"
nfltr orch task steer --task TASK_ID --message "narrow scope"
nfltr orch task artifact get --task TASK_ID --artifact-id AID --output PATH
nfltr orch task children aggregate --parent TASK_ID --json

Flags

spec

Create, validate, or decompose an orchestration spec before starting it.

nfltr orch spec template --name my-run
nfltr orch spec validate ./objective.json [--json]
nfltr orch spec decompose --goal "rename foo to bar across cli and docs" [--json]

fleet

Fleet operations for worker pools: status dashboards, worker inventory, pings, version upgrades, drain/undrain, and configuration drift detection.

nfltr orch fleet status [--json]
nfltr orch fleet workers [--flavor codex] [--json]
nfltr orch fleet ping [--json]
nfltr orch fleet top [--refresh-interval 2s]
nfltr orch fleet drift [--json]
nfltr orch fleet drain --worker POOL_ID
nfltr orch fleet upgrade --all
nfltr orch fleet restart-stale --workers POOL_ID
nfltr orch fleet wait --condition ready

queue

Use the local YAML queue runner for backlog-style orchestration where each ready item runs in its own Git worktree.

nfltr orch queue init
nfltr orch queue validate
nfltr orch queue plan
nfltr orch queue run --once
nfltr orch queue status --json

hitl

Inspect pending human-intervention work across approvals, questions, escalations, reviews, and exceptions.

nfltr orch hitl list --kind approval --json
nfltr orch hitl list --kind question --worker WORKER_ID

admin and lab

Admin commands handle local cleanup and task-store maintenance. Lab commands keep experimental and dogfood drivers out of the primary lifecycle path.

nfltr orch admin cleanup --base-dir .nfltr/worktrees --dry-run
nfltr orch admin task-store stats --json
nfltr orch admin task-store vacuum --before 7d --dry-run
nfltr orch lab fanout status --json
nfltr orch lab frontier --help

Examples

# List active implementer tasks in a batch
nfltr orch task list --filter role=implementer --filter batch_id=iter-78 --active

# Inspect a relay-backed task snapshot plus compact timeline
nfltr orch task status --task TASK_ID --events 20

# Resume event audit after the last reviewed relay sequence
nfltr orch task events --task TASK_ID --tail 50 --since 120

# Dispatch with transient retry budget
nfltr orch start worker --retry-on-transient 3 --worker impl-1 --role implementer --objective "..."

# Validate a spec before running
nfltr orch spec validate ./mission.json

# Monitor live orchestration load
nfltr orch fleet top --refresh-interval 3s

# Detect worker config drift vs planner expectations
nfltr orch fleet drift --json

# Task store maintenance
nfltr orch admin task-store stats --json
nfltr orch admin task-store vacuum --before 7d --dry-run

# Child task fan-in
nfltr orch task children aggregate --parent TASK_ID --json

nfltr version

Print the version string.

nfltr version
# → nfltr dev

Flags

nfltr demo

Interactive feature showcase — 10 numbered sections covering every capability with copy-pasteable commands. Shows the current platform, version, and auto-generated agent ID. Requires no API key or network connection.

nfltr demo

nfltr share — Instant Ephemeral URL new

Create an instant, ephemeral URL to share text, a file, or a directory. Content served through the tunnel until Ctrl+C or auto-expiration.

nfltr share [text|file|dir] [flags]

Flags

Examples

# Share text — wraps in a styled HTML page with copy button
nfltr share "error: connection refused on port 5432"

# Pipe from stdin
echo "build log" | nfltr share
git diff | nfltr share

# Share a file for download
nfltr share ./crash.log

# Share a directory with file listing
nfltr share ./dist/

# Auto-expire after 30 minutes
nfltr share "temporary secret" --expire 30m

# Password-protected
nfltr share ./secrets.env --share-auth admin:s3cret

# Plain text (curl-friendly)
nfltr share "data" --raw

nfltr watch — Live Command Dashboard new

Run a command periodically and stream live-updating output via a share URL. Like watch + tail -f combined, accessible from anywhere via Server-Sent Events.

nfltr watch [flags] <command> [args...]

Flags

Endpoints served

Examples

# Monitor Kubernetes pods
nfltr watch "kubectl get pods"

# Disk usage with 5-second refresh
nfltr watch --interval 5s df -h

# Docker container status
nfltr watch "docker ps --format 'table {{.Names}}\t{{.Status}}'"

# Auto-expire after 1 hour
nfltr watch --expire 1h "uptime"

# Password-protected dashboard
nfltr watch --basic-auth admin:secret "top -b -n 1"

nfltr clipboard — Cross-Machine Clipboard new

Sync clipboard content between machines via A2A messaging.

nfltr clipboard <command> [flags]

Sub-commands

Flags

Examples

# Copy local clipboard to a work machine
nfltr clipboard copy work-laptop

# Copy specific text
nfltr clipboard copy work-laptop "some text to share"

# Pipe text to clipboard
cat secret.env | nfltr clipboard copy work-laptop

# Retrieve clipboard from remote machine
nfltr clipboard paste work-laptop

# Output to stdout instead of local clipboard
nfltr clipboard paste work-laptop --stdout

nfltr notify — Desktop Notifications new

Send desktop notifications to remote agents, listen for incoming notifications, or watch a command and notify when done.

nfltr notify <command> [flags]

Sub-commands

Flags

Examples

# Send a notification to your work laptop
nfltr notify send work-laptop "Build finished!"

# With a custom title
nfltr notify send work-laptop "Tests passed" --title "CI"

# Listen for incoming notifications
nfltr notify listen --name my-laptop

# Run a command and notify when done
nfltr notify watch work-laptop make test
nfltr notify watch work-laptop -- long-running-script.sh

nfltr ai — Remote AI CLI new

Run an AI CLI tool (Claude, Copilot, etc.) in an interactive PTY session exposed via a web UI. Supports text/voice input and screenshot capture for vision-capable models.

nfltr ai [command] [args...] [flags]

Flags

Examples

# Run Claude CLI with web terminal UI (default)
nfltr ai claude

# Copilot with chat-style interface
nfltr ai copilot --mode chat --basic-auth admin:secret

# Custom AI tool with working directory
nfltr ai -- custom-ai-tool --verbose --cwd ~/project

UI modes

nfltr ssh-config — SSH Config Helper new

Generate and manage SSH Host blocks in ~/.ssh/config so you can ssh <agent-name> directly.

nfltr ssh-config <agent-name> [flags]

Flags

Examples

# Add SSH config for an agent
nfltr ssh-config my-server --user admin
# Then simply:
ssh my-server

# Preview without modifying
nfltr ssh-config my-server --print
# Output:
# Host my-server
#   ProxyCommand nfltr ssh-proxy --name %h --port %p
#   User admin

# Remove an agent's config
nfltr ssh-config my-server --remove

nfltr replay — HTTP Traffic Replay new

Replay HTTP requests captured by nfltr http --record against a local or remote server. Useful for reproducing bugs, load testing, or service migration verification.

nfltr replay <capture-file> [flags]

Flags

Examples

# Replay all captured traffic
nfltr replay nfltr-capture-20260325-120000.json

# Replay against a different server
nfltr replay capture.json --target http://localhost:3000

# Only POST requests, with response bodies
nfltr replay capture.json --method POST --verbose

# Filter by path with 100ms delay
nfltr replay capture.json --path /api/users --delay 100

# Preview without executing
nfltr replay capture.json --dry-run

nfltr help — Command Help

Print usage for a top-level command or subcommand. Equivalent to passing -h / --help on most commands.

nfltr help [command]
nfltr http --help

nfltr update — Self-Update new

Update nfltr to the latest version. Detects OS/architecture automatically and performs an atomic binary replacement.

nfltr update [flags]

Flags

Examples

# Update to latest version
nfltr update

# Check for updates without installing
nfltr update --check
# → Current: vX.Y.Z, Latest: vX.Y.Z (update available)

nfltr completion — Shell Completions new

Generate shell completion scripts for bash or zsh.

nfltr completion <bash|zsh>

Examples

# Bash — add to ~/.bashrc
eval "$(nfltr completion bash)"

# Zsh — add to ~/.zshrc
eval "$(nfltr completion zsh)"

Authentication

nfltr supports multiple authentication methods, tried in order:

1. --api-key flag — highest priority
2. NFLTR_API_KEY environment variable
3. --key-name flag — look up a named key from config
4. Config file — active key in ~/.config/nfltr/nfltr.json
5. mTLS certificates — --tls-cert, --tls-key, --tls-ca

API Key Authentication

The server administrator creates API keys via the admin dashboard or admin API. Each key is bound to an agent identity.

# Save once (or save multiple keys with --name)
nfltr config add-api-key YOUR_KEY
nfltr config add-api-key FRIEND_KEY --name alice

# All subsequent commands use the active key automatically
nfltr http 8080
nfltr status

# Or use a specific named key per-command
nfltr http 8080 --key-name alice

mTLS Authentication

For zero-trust environments without API keys:

nfltr http 8080 \
  --tls-cert client.crt \
  --tls-key client.key \
  --tls-ca ca.crt \
  --server grpc.yourcompany.com:443

Agent identity is derived from the certificate Common Name (CN).

Features

Share URLs

Share URLs are enabled by default. Every nfltr http or nfltr command session automatically gets a temporary public URL with a memorable name (e.g., https://vivid-hawk.nfltr.xyz/). Share URLs:

• Are accessible without authentication
• Use word-pair subdomains for easy sharing
• Expire when the agent disconnects
• Are revoked automatically on disconnect

nfltr http 8080
# → Share URL: https://vivid-hawk.nfltr.xyz/

# Disable with --no-share:
nfltr http 8080 --no-share

Multi-Backend Routing

Route different URL paths to different local services:

nfltr http 8080 \
  --route /api=3000 \
  --route /ws=4000 \
  --route /admin=https://localhost:9443

Verbose Request Logging

With --verbose, every proxied request is logged:

[1] GET / → http://localhost:8080/ → 200 (4521 bytes, txn=abc123)
[2] GET /style.css → http://localhost:8080/style.css → 200 (1200 bytes, txn=def456)
[3] POST /api/login → http://localhost:3000/api/login → 200 (89 bytes, txn=ghi789)

Auto-Reconnect

nfltr automatically reconnects when the connection drops:

• Default: 12 retry attempts with 5-second intervals
• Configure: --retries 30 --retry-wait 10
• Total resilience window: retries × retry-wait seconds

Duration Limit

Auto-stop after a fixed duration (useful for demos):

nfltr http 8080 --duration 3600  # Stop after 1 hour

Health Endpoint

nfltr exposes a local HTTP health endpoint (default :29501) for integration with monitoring tools:

nfltr http 8080 --health-addr :9999
# Health check: http://localhost:9999/health

Environment Variables

Quick Command Map