CLI Reference nfltr

Complete reference for the nfltr command-line tool — expose local services to the internet through encrypted tunnels.

Quick Start

# 1. Save your API key (obtain from the admin dashboard or your admin)
nfltr config add-api-key YOUR_API_KEY

# 2. Start a local service (e.g. on port 8080)
python3 -m http.server 8080

# 3. Expose it
nfltr http 8080

Your service is now reachable at https://nfltr.xyz/browse/<agent-id>/.

To skip the browse auth wall and get a public URL:

nfltr http 8080 --share

This prints a URL like https://vivid-hawk.nfltr.xyz/ that anyone can access without authentication.

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

Examples

# Basic — expose port 8080
nfltr http 8080

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

# Public share URL — no auth needed for visitors
nfltr http 8080 --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

# Self-hosted server
nfltr http 8080 --server my-server.local:9090 --tls=false

Connection banner

nfltr                  v1.0.14
Agent ID               myapp
Forwarding             https://nfltr.xyz/browse/myapp/ → http://localhost:8080
Share URL              https://vivid-hawk.nfltr.xyz/

Waiting for requests... (press Ctrl+C to stop)
[1] GET  → http://localhost:8080 → 200 (4521 bytes)
[2] GET  → http://localhost:8080/style.css → 200 (1200 bytes)

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 v1.0.17 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

# Non-TLS (self-hosted server without TLS)
nfltr tcp-connect my-ssh 22 --listen :2222 --server my-server.local:8080 --tls=false

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 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 with a share URL
nfltr command python3 myscript.py --share

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

# GitHub Copilot CLI as a remote AI assistant:
nfltr command --name copilot --share --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 --share --body-as-arg -p \
  --cwd ~/projects/frontend copilot -- --allow-all-tools
nfltr command --name copilot-backend --share --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 a2a — Agent-to-Agent Communication new

Direct messaging between agents connected to the same server. Supports unary send/receive, persistent listening, and bidirectional streaming.

nfltr a2a <command> [flags]

Sub-commands

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 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 status
  Version:    dev
  Server:     grpc.nfltr.xyz:443
  URL:        https://nfltr.xyz
  Status:     online
  Latency:    668ms

nfltr status --api-key YOUR_KEY
  ...
  Connected Agents:
    - myapp (connected)
    - test-cli (connected)

nfltr diagnose — Connectivity Diagnostics

Run a comprehensive connectivity test, similar to ngrok diagnose.

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 diagnose
  Server: grpc.nfltr.xyz:443

  Testing DNS resolution for nfltr.xyz...           OK  (172.67.xxx.xxx)
  Testing HTTP connectivity to https://nfltr.xyz... OK  (200)
  Testing HTTPS/TLS for nfltr.xyz:443...            OK  (TLS 1.3)
  Testing gRPC port grpc.nfltr.xyz:443...           OK
  Testing TLS handshake grpc.nfltr.xyz:443...       OK  (TLS 1.3)
  Measuring round-trip latency...                   OK  (621ms)

  All 6 tests passed.

nfltr config — Configuration Management

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

nfltr config <command>

Sub-commands

Examples

# Save API key
nfltr config add-api-key rpc_abc123...

# Check current config
nfltr config check

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

Config file format

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

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

nfltr keys — API Key Management

Manage API keys offline (reads/writes the key file directly, no running server required).

nfltr keys <command> [flags]

Sub-commands

Common flags

Examples

# Generate a key for an agent
nfltr keys generate --name myagent
#   Agent ID:   myagent
#   API Key:    rpc_abc123...

# List all keys
nfltr keys list
#   AGENT ID         KEY PREFIX           CREATED
#   --------         ----------           -------
#   myagent          rpc_abc123...        2026-03-21T10:00:00Z

# Revoke a key
nfltr keys revoke --name myagent

nfltr pricing — Cost Estimation new

Deterministic cost calculator for nfltr.xyz cloud usage. All calculations run locally — no network calls required.

nfltr pricing <subcommand> [flags]

Sub-commands

Examples

# Single agent, 1 month, 5 GB egress, 100K requests
nfltr pricing estimate --agents 1 --hours 730 --egress-gb 5 --requests 100000

# Enterprise: 50 agents, heavy traffic, JSON output
nfltr pricing estimate --agents 50 --hours 30000 --egress-gb 700 \
  --tcp-egress-gb 200 --requests 10000000 --tcp-sessions 50000 --json

# HA multi-pod: 20 agents, 3 pods
nfltr pricing estimate --agents 20 --hours 14600 --egress-gb 150 \
  --requests 2000000 --pods 3 --json

# Show rate card
nfltr pricing rates

nfltr version

Print the version string.

nfltr version
# → nfltr version dev

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

Authentication

nfltr supports multiple authentication methods, tried in order:

1. --api-key flag — highest priority
2. NFLTR_API_KEY environment variable
3. Config file — ~/.config/nfltr/nfltr.json
4. 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
nfltr config add-api-key YOUR_KEY

# All subsequent commands use it automatically
nfltr http 8080
nfltr status

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 my-server.local:9090

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

Features

Share URLs

The --share flag requests 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
# → Share URL: https://vivid-hawk.nfltr.xyz/

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  /              → 200 (4521 bytes, 12ms)
[2] GET  /style.css     → 200 (1200 bytes, 3ms)
[3] POST /api/login     → 200 (89 bytes, 45ms)
[4] GET  /missing       → 404 (22 bytes, 2ms)

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

Self-Hosted Server

When running your own nfltr server, point the agent at it:

# With TLS
nfltr http 8080 --server my-server.example.com:9090

# Without TLS (local/dev)
nfltr http 8080 --server localhost:9090 --tls=false

# With mTLS
nfltr http 8080 \
  --server my-server.local:9090 \
  --tls-cert agent.crt \
  --tls-key agent.key \
  --tls-ca ca.crt

Comparison with ngrok