Skip to main content

Command Line Interface (fs_cli)

Table of Contents (click to expand)

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
/quitThese all result in disconnecting from the FreeSWITCH command line./quit
/eventSubscribe to FreeSWITCH events./event allThis command corresponds to the event command in mod_event_socket.
/noeventsUnsubscribe from all events (previously subscribed to using /event)./noeventsThis command corresponds to the noevents command in mod_event_socket.
/nixeventSuppress 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 HEARTBEATThis command corresponds to the nixevent command in mod_event_socket.
/logSet log level of the FreeSWITCH deamon.0 - CONSOLE 1 - ALERT 2 - CRIT 3 - ERR 4 - WARNING 5 - NOTICE 6 - INFO 7 - DEBUG/log alert/log 1This 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.
/nologDisable logging./nologThis command corresponds to the nolog command in mod_event_socket.
/uuidFilter logs for a single call (specified by its UUID)./uuid 6936d2ad-bea3-40b3-9de3-34024404e8d4
/filterSpecify what events to listen to by event header value./filter <EventHeader> <ValueToFilter>/filter Event-Name HEARTBEAT/filter Unique-ID d29a070f-40ff-43d8-8b9d-d369b2389dfeThis command corresponds to the filter command in mod_event_socket.
/filter deleteDelete 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-IDThis 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
/debugSame 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

| Option | Description | Example | | | | | | | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ------- | ------ | ---- | ----- | -------------------------------- | | | host => <hostname> | Host to connect (default is | host => | | | | | | | | 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 | false | Disable logging | | | | | | | | | retry => true | false | Retry connection on failure every two seconds until connected (or until 2 minutes has passed) | | | | | | | | | reconnect => true | false | Reconnect if disconnected | | | | | | | | | debug => <0 .. 7> | Debug Level (0 - 7) | | | | | | | | | batchmode => true | false | Batch modeTODO 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 | | | | | | | | | key_f<n> | Set F1 - F12 keys for a certain functionality.Default key-bindingsF1 = 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


See this JIRA for an issue I faced: FS-7718 -Authenticate to see issue details 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. Posted by jungleboogie at Jun 23, 2015 22:55