Introduction to SWSH (SignalWire interactive shell)

SWSH (SignalWire interactive SHell) is a command line utility written in Python to interface with SignalWire APIs. SWSH is built to easily configure and manage SignalWire Spaces from a command-line environment.

SWSH is extremely useful in scripting contexts, and allows the user to perform repeated tasks quickly and efficiently by passing commands into SWSH.

Prerequisites

Before you begin, ensure you have the following prerequisites:

A free SignalWire Account
SignalWire API Credentials: Copy your Project ID and API Token from the API tab of your SignalWire Dashboard.
Python 3 (or later): Python is required to install SWSH in a standalone manner.
Docker Desktop is required for installing SWSH as a part of the SignalWire WireStarter container. Docker is not required for installing the standalone Python package.

Installation

SWSH can be installed in two ways.

Standalone: If you wish to use SWSH by itself, install its Python package.
With WireStarter: SWSH can also be installed with our WireStarter Docker container, which also sets up the SignalWire SDKs and sets up a convenient development and testing environment.

Standalone Installation

MacOS or Linux

Windows

Install SWSH standalone if you’re looking for a scriptable SignalWire CLI without the additional development and testing features provided by WireStarter.

Python3 is required for the SWSH standalone installation. We also recommend using the python3 venv module, but it isn’t required.

Create a new Python virtual environment

This command uses the venv module to create a new Python virtual environment named “swsh”. Before running it, navigate to the directory where you wish to store the swsh virtual environment.

$ python3 -m venv swsh

Activate the SWSH virtual environment

This command activates the swsh virtual environment you just created. This changes your shell’s environment to use the Python and pip binaries within this environment, isolating your Python setup from the system-wide Python installation.

$ source swsh/bin/activate

Install SWSH

This command installs the swsh package and its dependencies inside the activated virtual environment.

We’re aware of an issue with Python 3.12 causing dependency issues. Avoid these issues by specifying version 3.11 for pip.

$ pip3.11 install swsh

Start the SWSH command prompt

Now that SWSH is installed, you can start a shell with it by running:

swsh

WireStarter (Docker Image) Installation

WireStarter is a Docker container which sets up the SignalWire SDKs and builds a development and testing environment for new developers. Install SWSH with WireStarter if you want to take advantage of WireStarter’s features.

The instructions for installing WireStarter using Docker are universal and will work on MacOS, Linux, and Windows.

Start Docker Desktop

Docker must be running at the start of the process.

Download and install WireStarter

WireStarter has been updated recently. If you’ve used WireStarter before, be sure to delete the previous version and reinstall the latest version of the container.

$ docker run --name wirestarter briankwest/wirestarter:latest

Start SWSH

This command starts a terminal UI which will prompt you for relevant IDs and tokens. It will walk you through configuring the development and testing environment. It then automatically enters SWSH.

Follow the prompts on screen to enter your SignalWire Space, Project ID, and API token. Your SignalWire Space is the subdomain that prefixes signalwire.com. If your Dashboard is accessed at https://spacename.signalwire.com/dashboard, you should enter spacename when prompted for your Space. Copy the Project ID and REST API token from the API pane of your SignalWire Dashboard.

If you don’t plan to set up a WireStarter example application, you can safely ignore both ngrok prompts by leaving them blank and hitting Enter or Return.

$ docker exec -ti wirestarter bash

Learn more about WireStarter by visiting its repository on GitHub.

Running SWSH

Now that SWSH is installed, you can run it at any time by entering this command:

$ swsh

The Project ID, API Token, and API Key must be correctly configured in order to use SWSH commands.

Startup Variables

The following variables can be set to streamline startup.
They are also required for running in Non-Interactive mode. If they are not set, SWSH will ask for them at startup.

Linux / MacOS:

$ export PROJECT_ID=<YOUR_PROJECT_ID>
$ export SIGNALWIRE_SPACE=<YOUR_SIGNALWIRE_SPACE>
$ export REST_API_TOKEN=<YOUR_REST_API_TOKEN>

Windows:

$ setx PROJECT_ID=<YOUR_PROJECT_ID>
$ setx SIGNALWIRE_SPACE=<YOUR_SIGNALWIRE_SPACE>
$ setx REST_API_TOKEN=<YOUR_REST_API_TOKEN>

Commands

This section defines all SWSH commands. Commands can be run interactively or non-interactively.

Interactive Commands

Interactive commands are done within the SWSH shell itself. For example:

Type swsh to enter the shell
Enter the following command: phone_number list

Scriptable (Non-Interactive) Commands

This type of command can be passed into SWSH, allowing for the output from SWSH to be passed back to the main shell. This type of SWSH command is ideal for scripting. Startup variables must be set in order to enable scriptable commands.

Scriptable commands use the same syntax as Interactive commands, but condensed into a single line. For example:

$ swsh phone_number list

Space

Manage your SignalWire Space using the following SWSH commands:

Command	Description
`space cd`	Change to the specified Space
`space show`	Show details about the current Space

Project

Manage the Project (and any subprojects) within a SignalWire Space using the following SWSH commands:

Command	Description
`project list`	Show a list of all projects in your SignalWire Space.
`project create`	Create a new Project.
`project update`	Update the Project details.
`project delete`	Delete a Project.

Domain Application

Domain Applications allow you to send SIP traffic to a custom domain and run specified logic. Manage Domain Applications within a SignalWire Project using the following commands:

Command	Description
`domain_application list`	List domain applications.
`domain_application create`	Create a new domain application.
`domain application update`	Update a domain application.
`domain application delete`	Delete a domain application.

Number Group

Number Groups are useful for configuring a set (or “group”) of numbers as a single entity. Manage Number Groups within a SignalWire Project using the following commands:

Command	Description
`number_group list`	List existing Number Groups in your Space.
`number_group create`	Create a new Number Group.
`number_group update`	Update an existing Number Group.
`number_group delete`	Delete a Number Group.

cXML Application

Manage cXML Applications within a SignalWire Project with these commands:

Command	Description
`laml_bin list`	List existing LaML bins.
`laml_bin create`	Create a new LaML bin.
`laml_bin update`	Update an existing LaML bin.
`laml_bin delete`	Delete a LaML bin.

Phone Number

Manage the SignalWire Phone Numbers within a SignalWire Project with these commands:

Command	Description
`phone_number list`	List the phone numbers associated with your Project.
`phone_number buy`	Buy a new phone number.
`phone_number update`	Update an existing phone number.
`phone_number delete`	Delete one of our phone numbers.
`phone_number lookup`	Look up and filter phone numbers.

SIP Endpoint

Manage SIP Endpoints within a SignalWire Project with these commands:

Command	Description
`sip_endpoint list`	List existing SIP Endpoints.
`sip_endpoint create`	Create a new SIP Endpoint.
`sip_endpoint update`	Update a SIP Endpoint.
`sip_endpoint delete`	Delete an existing SIP Endpoint.

SIP Profile

Manage SIP Profiles within a SignalWire Project with these commands:

Command	Description
`sip_profile list`	List SIP Profiles.
`sip_profile update`	Update SIP Profiles.

Make a Call

Initiate a phone call between two parties using a SignalWire Project.

The Sending Phone Number must belong to the project.

$ send_call --from-num <calling number> --to-num <destination number> --url <dialplan url>

Request Call Records

Retrive Call Records on a SignalWire Project

Command	Description
`get_call`	Retrieves a detailed list of recent calls.
`get_call --id <SID of call>`	Retrieves call information. Replace `<SID of call>` with the SID (SignalWire ID) of the desired call.
`get_call --all-active`	Retrieves call information for all active calls.

Send a Text

Transmit a text message to a destination using a SignalWire Project.

The Sending Phone Number must belong to the project.

$ send_text --from-num <texting number> --to-num <destination number> --text-body "<Text Body>"

Clear

Clears the screen.

clear

Exit

Exit the swsh subshell.

exit

Have a question or bug to report?

Help us improve SWSH for your use case by reporting an Issue on the SWSH GitHub Repository.