client cli

client reference

the funnel client is the command-line tool you use on your local machine to connect your service to a funnel server.

primary commands

🌐 funnel http

create an http tunnel (primary command)

⚙️ funnel config

manage client configuration

📋 funnel version

display version information

`funnel http`

this is the primary command for creating an http tunnel.

basic syntax

funnel http [address:port | port] [flags]

arguments

flexible addressing

you can specify either just a port or a full address:port combination.

[address:port | port] (required): the local address of the service you want to expose.

if you provide just a port (e.g., 3000), it will default to localhost:3000.
you can provide a full address (e.g., 127.0.0.1:8080).

flags

flag	shorthand	default	description
`--server`	`-s`	(from config)	the url of the remote funnel server. use `http://` or `https://`. overrides config.
`--id`	`-i`	(randomly generated)	the custom subdomain to request for the tunnel.
`--inlet`		`default`	the inlet configuration to use from your config file.
`--token`	`-t`	(from config)	authentication token for the server. overrides config.
`--help`	`-h`		show help for the command.

configuration

the funnel client supports configuration files to save and reuse server endpoints. this allows you to quickly switch between different tunnel servers without specifying the full URL each time.

config file location

the client looks for configuration in the following order:

$XDG_CONFIG_HOME/funnel/config.toml (if XDG_CONFIG_HOME is set)
~/.config/funnel/config.toml (default location)

easy setup

use funnel config set-server and funnel config set-token to create and manage your config file automatically.

config file format

configuration uses TOML format with the following structure:

[inlets.default]
server = "http://localhost:8080"
domain = "localhost:8080"
token = "sk_your_token_here"

[inlets.production]
server = "https://api.tunneling.dev"
domain = "tunneling.dev"
token = "sk_production_token"

[inlets.staging]
server = "https://staging.tunneling.dev"
domain = "staging.tunneling.dev"
token = "sk_staging_token"

inlet configuration

each inlet section contains:

server (required): the URL of the tunnel server
domain (optional): the domain for display purposes
token (optional): authentication token for the server

token security

the token is stored in plain text in the config file. the file is created with restricted permissions (0600), but ensure your machine is secure.

using inlets

inlet usage

use the --inlet flag to specify which configuration to use, or omit it to use the default inlet.

# use default inlet
funnel http 3000

# use specific inlet
funnel http 3000 --inlet production

# override config with command line
funnel http 3000 --inlet production --server https://custom.example.com

configuration required

if no configuration file exists or the specified inlet doesn't exist, the client will require you to specify the --server flag explicitly.

examples

expose a service on port 3000, using the default inlet:

funnel http 3000

default behavior

this will use the default inlet from your config file, or localhost:8080 if no config exists.

use a specific inlet configuration:

# use production inlet
funnel http 3000 --inlet production

# use staging inlet with custom id
funnel http 3000 --inlet staging --id my-app-staging

configuration workflow

perfect for switching between different environments (development, staging, production) without remembering server URLs.

connect to a remote server with a custom subdomain:

funnel http 3000 --server https://my-server.com --id my-app-demo

secure connection

use https:// for secure connections when connecting to a server with TLS enabled.

expose a service on a different host and port:

funnel http 192.168.1.100:8000 --server http://tunnel.mycompany.com:8080 --id staging-api

network services

you can expose services running on other machines in your network, but ensure they're accessible from your client machine.

`funnel config`

manage client configuration, including server urls and authentication tokens.

subcommands

save an authentication token to your config file:

funnel config set-token sk_your_token_here

# for a specific inlet
funnel config set-token sk_prod_token --inlet production

token storage

the token is stored in plain text in the config file. the file is created with restricted permissions (0600).

save a server url to your config file:

funnel config set-server https://tunnel.example.com

# for a specific inlet
funnel config set-server https://prod.tunnel.io --inlet production

display the current configuration:

funnel config show

# output:
# Config file: ~/.config/funnel/config.toml
#
# [default]
#   server: http://localhost:8080
#   token:  sk_7Fj2kL...
#
# [production]
#   server: https://tunnel.example.com
#   token:  sk_prod_t...

show the config file path:

funnel config path

# output:
# /home/user/.config/funnel/config.toml

config flags

flag	default	description
`--inlet`	`default`	the inlet to configure

`funnel version`

displays the version of the funnel client.

funnel version

version check

useful for verifying your installation and checking for updates.

usage patterns

development workflow

🔧 local development

funnel http 3000 --inlet local

🧪 testing

funnel http 8080 --inlet staging

🎯 demos

funnel http 5000 --inlet production

common scenarios

expose your local development server:

# react development server
funnel http 3000 --inlet local --id my-react-app

# next.js development server  
funnel http 3000 --inlet local --id my-nextjs-app

# vite development server
funnel http 5173 --inlet local --id my-vite-app

expose your local api for testing:

# express api server
funnel http 8000 --inlet staging --id my-api-v1

# django development server
funnel http 8000 --inlet staging --id django-api

# flask development server
funnel http 5000 --inlet staging --id flask-api

expose your local server for mobile app testing:

# react native metro bundler
funnel http 8081 --inlet local --id rn-bundler

# local api for mobile app
funnel http 3000 --inlet staging --id mobile-api

mobile testing

perfect for testing your mobile app against a local backend without complex network configuration.

troubleshooting

common issues

if you encounter connection issues, check these common problems:

connection refused: ensure the server is running and accessible
tunnel id taken: try a different --id or let the system generate one
local service not found: verify your local service is running on the specified port
firewall blocking: check that your firewall allows outbound websocket connections
inlet not found: verify the inlet exists in your config file or use --server to override
config file not found: create a config file manually at ~/.config/funnel/config.toml or use --server flag

need help?

for server-specific configuration, see the server CLI reference.

Last updated: December 23, 2025

by karol-broda