For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Log inSign up
Support
PlatformCallingAIMessagingTools
PlatformCallingAIMessagingTools
  • Tools
    • Overview
    • SWSH
    • WireStarter
LogoLogoSignalWire Docs
Log inSign up
Support
On this page
  • Prerequisites
  • Installation
  • Standalone Installation
  • WireStarter (Docker Image) Installation
  • Running SWSH
  • Startup Variables
  • Commands
  • Interactive Commands
  • Scriptable (Non-Interactive) Commands
  • Space
  • Project
  • Domain Application
  • Number Group
  • cXML Application
  • Phone Number
  • SIP Endpoint
  • SIP Profile
  • Make a Call
  • Request Call Records
  • Send a Text
  • Clear
  • Exit
  • Have a question or bug to report?
Tools

Introduction to SWSH (SignalWire interactive shell)

|View as Markdown|Open in Claude|
Was this page helpful?
Edit this page
Previous

Introduction to WireStarter

Next
Built with

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.

The SWSH command prompt.

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.

  1. Standalone: If you wish to use SWSH by itself, install its Python package.
  2. 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.

  1. 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
  1. 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
  1. 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
  1. 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.

  1. Start Docker Desktop

Docker must be running at the start of the process.

  1. 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
  1. 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:

  1. Type swsh to enter the shell
  2. 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:

CommandDescription
space cdChange to the specified Space
space showShow details about the current Space

Project

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

CommandDescription
project listShow a list of all projects in your SignalWire Space.
project createCreate a new Project.
project updateUpdate the Project details.
project deleteDelete 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:

CommandDescription
domain_application listList domain applications.
domain_application createCreate a new domain application.
domain application updateUpdate a domain application.
domain application deleteDelete 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:

CommandDescription
number_group listList existing Number Groups in your Space.
number_group createCreate a new Number Group.
number_group updateUpdate an existing Number Group.
number_group deleteDelete a Number Group.

cXML Application

Manage cXML Applications within a SignalWire Project with these commands:

CommandDescription
laml_bin listList existing LaML bins.
laml_bin createCreate a new LaML bin.
laml_bin updateUpdate an existing LaML bin.
laml_bin deleteDelete a LaML bin.

Phone Number

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

CommandDescription
phone_number listList the phone numbers associated with your Project.
phone_number buyBuy a new phone number.
phone_number updateUpdate an existing phone number.
phone_number deleteDelete one of our phone numbers.
phone_number lookupLook up and filter phone numbers.

SIP Endpoint

Manage SIP Endpoints within a SignalWire Project with these commands:

CommandDescription
sip_endpoint listList existing SIP Endpoints.
sip_endpoint createCreate a new SIP Endpoint.
sip_endpoint updateUpdate a SIP Endpoint.
sip_endpoint deleteDelete an existing SIP Endpoint.

SIP Profile

Manage SIP Profiles within a SignalWire Project with these commands:

CommandDescription
sip_profile listList SIP Profiles.
sip_profile updateUpdate 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

CommandDescription
get_callRetrieves 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-activeRetrieves 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.