FreeSWITCH CLI: Console and fs_cli Reference

FreeSWITCH provides two primary command-line interfaces: the interactive console that runs in the foreground alongside the process, and fs_cli, a standalone client that connects to a running FreeSWITCH instance over the Event Socket Layer (ESL). Both give you access to the same set of API commands — the console is ideal for development and direct server access, while fs_cli is the standard tool for remote or scripted administration.

Starting FreeSWITCH

The freeswitch binary accepts a number of flags that control how the process starts, where it looks for configuration, and what privileges it runs under. All flags are optional; running freeswitch without arguments starts it in interactive console mode.

Run Mode Flags

-c

Start in interactive console mode and stay in the foreground. This is the default behavior when no run-mode flag is given.

-nc

Daemonize — disable the interactive console and send the process to the background.

-ncwait

Like -nc, but the parent process waits until FreeSWITCH finishes startup before exiting. Useful in init scripts.

-nf

Stay in the foreground without attaching an interactive console. Useful with process supervisors such as systemd or runit.

Control Flags

Flag	Description
`-h`	Show inline help and exit.
`-version`	Print the version string and exit immediately.
`-stop`	Send a stop signal to a running background instance.
`-reincarnate`	Automatically restart the process after an uncontrolled exit.
`-reincarnate-reexec`	Like `-reincarnate`, but re-executes the binary via `execv` on restart.

Directory Override Flags

These flags let you run multiple FreeSWITCH instances or relocate specific data directories without editing configuration files.

Flag	Description
`-base <dir>`	Set the base prefix directory for all paths.
`-cfgname <file>`	Set the pathname to the main configuration file.
`-conf <dir>`	Directory for configuration files (default: `/etc/freeswitch`).
`-log <dir>`	Directory for log files.
`-run <dir>`	Directory for temporary runtime files (PID file, etc.).
`-db <dir>`	Directory for internal database files.
`-mod <dir>`	Directory where runtime modules are loaded from.
`-htdocs <dir>`	Directory for htdocs (HTTP server).
`-scripts <dir>`	Directory for call-control scripts.
`-temp <dir>`	Directory for temporary files.
`-grammar <dir>`	Directory for grammar files.
`-recordings <dir>`	Directory for call recordings.
`-storage <dir>`	Directory for voicemail storage.
`-sounds <dir>`	Directory for sound/prompt files.

Privilege and Performance Flags

Flag	Description
`-u <user>`	Call `setuid` after startup to drop root privileges to the given user.
`-g <group>`	Call `setgid` after startup to drop root privileges to the given group.
`-rp`	Enable realtime scheduling priority for the main process threads.
`-lp`	Enable low scheduling priority.
`-np`	Enable normal scheduling priority (explicit default).
`-vg`	Run the switch process under Valgrind for memory debugging.
`-nonat`	Disable the NAT detection checks performed at startup.
`-nonatmap`	Disable automatic NAT port mapping.
`-nocal`	Disable the system clock calibration performed at startup.
`-nort`	Disable use of `CLOCK_REALTIME`.
`-heavy-timer`	Use a more expensive but potentially more accurate system timer.
`-nosql`	Disable internal SQL usage (may limit functionality).
`-core`	Enable core dump generation on crash (also requires appropriate `ulimit` settings).

Example: Starting in Daemon Mode

# Start as a daemon, wait for full startup before returning
freeswitch -ncwait -u freeswitch -g freeswitch

# Start interactively with a custom config directory
freeswitch -c -conf /opt/freeswitch/conf

# Stop a running background instance
freeswitch -stop

fs_cli

fs_cli is a separate binary that connects to a running FreeSWITCH instance over the Event Socket Layer on TCP port 8021. It provides the same interactive console experience — including tab completion and command history — without requiring direct access to the server process.

Connection Flags

Flag	Description
`-H <host>`	Hostname or IP address to connect to (default: `127.0.0.1`).
`-P <port>`	ESL port to connect on (default: `8021`).
`-p <password>`	ESL password (default: `ClueCon` — change this in production).
`-x <cmd>`	Execute a single command non-interactively and exit.
`-q`	Quiet mode — suppress banner output.
`-t <ms>`	Timeout in milliseconds for ESL connection.

Connecting to a Local Instance

fs_cli -H 127.0.0.1 -P 8021 -p ClueCon

Running a Single Command Non-Interactively

# Check status and exit — useful in scripts and monitoring checks
fs_cli -x "status"

# Reload XML configuration from a shell script
fs_cli -x "reloadxml"

# Retrieve active channel count
fs_cli -x "show channels count"

Inside fs_cli, press Tab to auto-complete API command names and module names. Use the Up/Down arrow keys to navigate command history, and type /help to list available meta-commands. Press F1–F12 to trigger the keybindings configured in switch.conf.xml.

Essential Console Commands

The following commands work identically whether you type them at the interactive console or pass them via fs_cli -x "...".

Status and Monitoring

status — Show uptime and session counts

Displays FreeSWITCH uptime, the number of active sessions, sessions per second, and peak session counts.

freeswitch> status

Example output:

UP 0 years, 1 day, 4 hours, 32 minutes, 18 seconds, 423 milliseconds, 815 microseconds
FreeSWITCH (Version 1.10.x) is ready
0 session(s) since startup
0 session(s) - peak 0, last 5min 0
0 sessions per second - peak 0, last 5min 0
min idle cpu 0.00/100.00

show channels — List active calls

Lists all currently active channels (legs) in the switch, including their UUID, state, caller ID, and destination.

freeswitch> show channels
freeswitch> show channels count

show registrations — SIP endpoint registrations

Displays all currently registered SIP endpoints, their contact URIs, expiry times, and user agents.

freeswitch> show registrations

show calls — Active bridged call pairs

Lists bridged call legs (as opposed to individual channels). Useful for seeing how many actual calls — not legs — are in progress.

freeswitch> show calls
freeswitch> show calls count

Sofia SIP Management

sofia status — SIP profile overview

Shows all loaded Sofia SIP profiles and their state (RUNNING, STOPPED), listening addresses, and gateway counts.

freeswitch> sofia status

sofia status profile internal — Detailed profile info

Dumps detailed information about a specific SIP profile including bindings, gateways, and settings.

freeswitch> sofia status profile internal
freeswitch> sofia status profile external

sofia profile internal reload — Reload a SIP profile

Reloads a SIP profile’s configuration without restarting FreeSWITCH. Changes to the profile XML are applied immediately.

freeswitch> sofia profile internal reload
freeswitch> sofia profile external restart

sofia global siptrace on — Enable SIP message tracing

Enables live SIP message tracing to the console for all profiles. Invaluable for debugging registration and call setup issues.

freeswitch> sofia global siptrace on
freeswitch> sofia global siptrace off

Configuration Reloading

reloadxml — Reload all XML configuration

Re-reads and re-parses all XML configuration files (dialplan, directory, config). No restart required. Module configuration requires a separate reload command.

freeswitch> reloadxml

reload <module> — Reload a specific module

Unloads and reloads a named module, applying any configuration changes. Does not affect other modules.

freeswitch> reload mod_sofia
freeswitch> reload mod_dialplan_xml

load / unload — Load or unload a module at runtime

Loads a module that is not currently running, or unloads one that is. Changes are not persistent across restarts — edit modules.conf.xml to make them permanent.

freeswitch> load mod_xml_curl
freeswitch> unload mod_xml_curl

Call Control

originate — Create a new outbound call

Creates a new call leg to an endpoint and connects it to an application or extension. This is the primary way to generate calls from the console.

# Call a SIP endpoint and play music on hold
freeswitch> originate sofia/internal/1000@192.168.1.100 &hold

# Call an endpoint and bridge it to another
freeswitch> originate sofia/internal/1000@192.168.1.100 &bridge(sofia/gateway/mycarrier/18005551234)

# Originate and drop into an IVR application
freeswitch> originate sofia/internal/1000@192.168.1.100 &playback(/tmp/welcome.wav)

uuid_kill — Hang up a call by UUID

Immediately terminates a specific channel identified by its UUID. Use show channels to find the UUID.

freeswitch> uuid_kill 3f6a1b2c-1234-4abc-8def-000000000001

uuid_bridge — Bridge two existing channels

Bridges two already-answered channels together, connecting their audio paths.

freeswitch> uuid_bridge 3f6a1b2c-1234-4abc-8def-000000000001 5a9b2c3d-5678-4def-9012-000000000002

System Control

log <level> — Set console log verbosity

Changes the verbosity of console log output at runtime. Level 0 silences all output; level 7 shows INFO and below; level 8 shows DEBUG.

freeswitch> log 7
freeswitch> log 0
freeswitch> log debug

fsctl pause / fsctl resume — Pause call processing

Temporarily suspends acceptance of new inbound calls. In-progress calls are not affected. Use fsctl resume to resume.

freeswitch> fsctl pause
freeswitch> fsctl resume

bgapi — Run a command in the background

Submits an API command for asynchronous execution. The result is delivered as an event rather than blocking the console.

freeswitch> bgapi originate sofia/internal/1000@192.168.1.100 &echo

version — Print FreeSWITCH version

Prints the exact version string of the running FreeSWITCH binary.

freeswitch> version

Console Keybindings

The default switch.conf.xml defines F-key bindings available in the interactive console:

Key	Command
F1	`help`
F2	`status`
F3	`show channels`
F4	`show calls`
F5	`sofia status`
F6	`reloadxml`
F7	`console loglevel 0` (silence)
F8	`console loglevel 7` (INFO)
F9	`sofia status profile internal`
F10	`sofia profile internal siptrace on`
F11	`sofia profile internal siptrace off`
F12	`version`

These bindings can be customized in the <cli-keybindings> section of conf/autoload_configs/switch.conf.xml.

Getting Started

Core Concepts

Configuration

Modules

Event Socket Layer

Operations

FreeSWITCH CLI: Console and fs_cli Reference

Starting FreeSWITCH

Run Mode Flags

-c

-nc

-ncwait

-nf

Control Flags

Directory Override Flags

Privilege and Performance Flags

Example: Starting in Daemon Mode

fs_cli

Connection Flags

Connecting to a Local Instance

Running a Single Command Non-Interactively

Essential Console Commands

Status and Monitoring

Sofia SIP Management

Configuration Reloading

Call Control

System Control

Console Keybindings

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Configuration

Modules

Event Socket Layer

Operations

Documentation Index

​Starting FreeSWITCH

​Run Mode Flags

-c

-nc

-ncwait

-nf

​Control Flags

​Directory Override Flags

​Privilege and Performance Flags

​Example: Starting in Daemon Mode

​fs_cli

​Connection Flags

​Connecting to a Local Instance

​Running a Single Command Non-Interactively

​Essential Console Commands

​Status and Monitoring

​Sofia SIP Management

​Configuration Reloading

​Call Control

​System Control

​Console Keybindings

Build docs developers (and LLMs) love

Starting FreeSWITCH

Run Mode Flags

Control Flags

Directory Override Flags

Privilege and Performance Flags

Example: Starting in Daemon Mode

fs_cli

Connection Flags

Connecting to a Local Instance

Running a Single Command Non-Interactively

Essential Console Commands

Status and Monitoring

Sofia SIP Management

Configuration Reloading

Call Control

System Control

Console Keybindings