Call Us Today! 877.742.2583

Page tree
Skip to end of metadata
Go to start of metadata

0. About

The fs_cli program is a Command-Line Interface that allows a user to connect to a running FreeSWITCH™ instance. The fs_cli program can connect to the FreeSWITCH™ process on the local machine or on a remote system. (Network connectivity to the remote system is, of course, required.)

The fs_cli program uses FreeSWITCH™ 's Event Socket Library (ESL) to tap into FreeSWITCH™'s event system to send commands issued by the user, and to collect the server responses to send to the display. The Event Socket Library (ESL), a C-based socket library, was developed for use with fs_cli, although a programmer could use this library for any C language program that needs to connect to the event socket. With the -x switch (see below) fs_cli can issue a command to the server, get a response, and then disconnect.

The fs_cli program can connect to FreeSWITCH™, whether it has been started as a service (TODO) or on the console (either background or foreground) (TODO), regardless of operating system.

1. Requirements

fs_cli requires mod_event_socket to be loaded in order to connect to the FreeSWITCH™ server.

Normally, the easiest way to check if a module is loaded is to use fs_cli 

$ fs_cli

freeswitch@tr2> module_exists mod_event_socket

# or
$ fs_cli -x 'module_exists mod_event_socket'

but in this case, for obvious reasons, check whether the mod_event_socket is enabled in modules.conf.xml (see Configuring FreeSWITCH).

The default mod_event_socket configuration binds to :: (i.e., to listen to connections from any host), which will work on IPv4 or IPv6. 

:: means that mod_event_socket will listen to connections from any host (see vanilla <conf_dir>/autoload_configs/event_socket.conf.xml configuration file in the SignalWire GitHub repository). There are obvious security risks, so one would want to change this (e.g., to localhost only, ::1 ), and perhaps also limit access via a firewall and/or ACL, as well as never using the default password.

2. Install

2.1 Server

The FreeSWITCH™ server will build and install the fs_cli client by default.

2.2 Client

The client can also be built without needing to build the entire FreeSWITCH™ server.

To build:

make current
cd libs/esl

To run:


3. Usage

3.1 Available switches

command syntax
  -?,-h --help                    Usage Information
  -H, --host=hostname             Host to connect (default is
  -P, --port=port                 Port to connect (default is "8021")
  -u, --user=user@domain          user@domain
  -p, --password=password         Password (default is "ClueCon")
  -i, --interrupt                 Allow Control-c to interrupt
  -x, --execute=command           Execute Command and Exit
  -l, --loglevel=command          Log Level (default is debug)
  -U, --log-uuid                  Include UUID in log output
  -S, --log-uuid-short            Include shortened UUID in log output
  -q, --quiet                     Disable logging
  -r, --retry                     Retry connection on failure every two seconds until connected (or until 2 minutes has passed)
  -R, --reconnect                 Reconnect if disconnected
  -d, --debug=level               Debug Level (0 - 7)
  -b, --batchmode                 Batch mode
  -t, --timeout                   Timeout for API commands (in miliseconds)
  -T, --connect-timeout           Timeout for socket connection (in miliseconds)
  -n, --no-color                  Disable color

3.2 Examples

3.2.1 Simple


fs_cli which connects to local machine using default username, password, and debug level.

3.2.2 Using profiles

fs_cli my_profile

Launches fs_cli using profile named "my_profile" found in .fs_cli_conf file (see section 5.3 below).

3.2.3 Sending a command and then logging off

fs_cli -x "sofia status profile internal"

Launches fs_cli and sends a command before logging off. The output of the above command looks like this:

$ fs_cli -x "sofia status profile internal"
Name internal
Domain Name N/A
Auto-NAT false
DBName sofia_reg_internal
Pres Hosts,
Dialplan XML
Context public
Challenge Realm auto_from
URL sip:mod_sofia@
BIND-URL sip:mod_sofia@;transport=udp,tcp
WS-BIND-URL sip:mod_sofia@;transport=ws
WSS-BIND-URL sips:mod_sofia@;transport=wss
HOLD-MUSIC local_stream://moh
DTMF-MODE rfc2833
CNG 13

4. Available commands


While connected, the user can issue any command in the FreeSWITCH API (which are all the commands exposed in the enabled modules and mod_commands).

See the console commands for example, exposed by mod_console .

freeswitch@tr2> console
console help
console loglevel [[0-7] | <loglevel_string>]
console uuid [on|off|toggle]
console json [on|off|toggle]
console colorize [on|off|toggle]

4.2 Forward slash (/) commands

Additionally, there are several commands that can be issued using a forward slash (/) character.

"slash" commandDescriptionExamplesNotes

These all result in disconnecting from the FreeSWITCH command line.







Subscribe to FreeSWITCH events.

/event allThis command corresponds to the event command in mod_event_socket.


Unsubscribe from all events (previously subscribed to using /event).

/noeventsThis command corresponds to the noevents command in mod_event_socket.


Suppress the specified type of event.

Useful when you want to allow /event all followed by nixevent <some_event> to see all but one type of event.

/nixevent HEARTBEAT

This command corresponds to the nixevent command in mod_event_socket.


Set log level of the FreeSWITCH deamon.

2 - CRIT
3 - ERR
6 - INFO

/log alert

/log 1

This command corresponds to the log command in mod_event_socket.

TODO So what is the point of console loglevel <level> ? The default log level is stated when fs_cli is started (which is 7 for debug), but console loglevel  will report NOTICE (i.e., 5).
However it is, /log seems to take precedence over the console  commands.


Disable logging./nologThis command corresponds to the nolog command in mod_event_socket.


Filter logs for a single call (specified by its UUID).

/uuid 6936d2ad-bea3-40b3-9de3-34024404e8d4


Specify what events to listen to by event header value.

/filter <EventHeader> <ValueToFilter>

/filter Event-Name HEARTBEAT

/filter Unique-ID d29a070f-40ff-43d8-8b9d-d369b2389dfe
This command corresponds to the filter command in mod_event_socket.
/filter delete

Delete previously set event filters.

/filter delete <EventHeader> <ValueToFilter>

If <ValueToFilter> is omitted, the command will delete all filters previously set for the specified event header.

/filter delete Event-Name HEARTBEAT
/filter delete Unique-ID d29a070f-40ff-43d8-8b9d-d369b2389dfe
/filter delete Unique-ID
This command corresponds to the filter delete command in mod_event_socket.
/logfilter <string>

Filter the logs by the given <string> . (The log levels are set by /log , see above.)

TODO What is the exact syntax? Does it accept regexes as well? I know that it takes anything that follows /logfilter literally, because adding double quotes to a string with space will actually look for double quotes in the log entries.

/logfilter Codec Activated
/logfilterDisable all logfilters./logfilter
/helpList available fs_cli  commands./help 
/debug <debug_level>

There are 8 debug levels (from 0 to 7) and the higher the number the more verbose the logs will become.

/debug <debug_level> is equivalent to

/log 7
/debug <debug_level>
/debug 3 
/debug Same as /debug 0 /debug 

For command-line editing, see "Command-Line Editing" section of mod_console. The details are the same as of SVN r13964.

5. Configuration

TODO The statements in this section need confirmation.  For example, tried to de-colorize the console logs by setting the relevant section to false in console.conf.xml (see mod_console) and in switch.conf.xml, while having no fs_cli.conf  anywhere in the system after a vanilla FreeSWITCH install.

5.1 switch.conf.xml

switch.conf.xml contains the core FreeSWITC configuration, see more there.

5.2 mod_console

mod_console and its configuration file, console.conf.xml also affect fs_cli, and some of the options are redundant with switch.conf.xml.

5.3 /etc/fs_cli.conf and ~/.fs_cli 

TODO This section definitely needs confirmation; the vanilla FreeSWITCH install doesn't have any fs_cli.conf (only ~/.fs_cli_history ), and the only intact fs_cli.conf file I could find is this.

Use fs_cli.conf to override existing configuration (/etc/fs_cli.conf for system-wide settings and ~/.fs_cli_conf for user-specific settings).

5.3.1 Format

The config file uses a simple INI-style layout and allows for multiple profiles. This allows one to access many FreeSWITCH™ systems from a single workstation.

; Put me in /etc/fs_cli.conf or ~/.fs_cli_conf
;overide any default options here
loglevel => 6
log-uuid => false
quiet => false
key_f1 => help
key_f2 => status
key_f3 => show channels
key_f4 => show calls
key_f5 => sofia status
key_f6 => reloadxml
key_f7 => /log console
key_f8 => /log debug
key_f9 => sofia status profile internal
key_f10 => sofia global siptrace on
key_f11 => sofia global siptrace off
key_f12 => version

host     =>
port     => 8021
password => secret_password
debug    => 7

host     =>
port     => 8021
password => someother_password
loglevel => info


5.3.2 Configuration options

host => <hostname>Host to connect (default is =>
port => <port>Port to connect (default is 8021)port => 8021
user => <username> user@domain
password => <password>Password (default is "ClueCon")password => ClueCon

interrupt => true | false

Allow Control-c to interrupt

execute => <command>Execute command and exit
loglevel => console | alert | crit | err | warning | notice | info | debug Set log Level (default is debug)
log-uuid => true | false Include UUID in log output
log-uuid-short => true | false Include shortened UUID in log output
quiet => true | falseDisable logging
retry => true | false Retry connection on failure every two seconds until connected (or until 2 minutes has passed)
reconnect => true | falseReconnect if disconnected
debug => <0 .. 7> Debug Level (0 - 7)
batchmode => true | false 

Batch mode

TODO What does this mean?

timeout => <milliseconds> Timeout for API commands (in miliseconds)
connect-timeout => <milliseconds> Timeout for socket connection (in miliseconds)
no-color => true | false Disable color

Set F1 - F12 keys for a certain functionality.

Default key-bindings

F1 = help
F2 = status
F3 = show channels
F4 = show calls
F5 = sofia status
F6 = reloadxml
F7 = console loglevel 0
F8 = console loglevel 7
F9 = sofia status profile internal
F10 = sofia profile internal siptrace on
F11 = sofia profile internal siptrace off
F12 = version
See example at 5.3.1 Format above.

6. Wish List

  • Option to see all output to include FS console output.
  • Option to see all output from all fs_cli instances connected to the FS box, plus the console.
  • Option to connect to more than one FS box.

7. See Also

1 Comment

  1. See this JIRA for an issue I faced: FS-7718 - Getting issue details... STATUS

    I was not able to connect to freeswitch on localhost with fs_cli until I copied the example conf file from /usr/src/freeswitch to /usr/loca/freeswitch.

    Maybe future releases won't require this but I'm writing here so at least I know how to resolve tfs_cli connection issues.