The PJSUA command line softphone is a versatile SIP user agent based on the PJSIP stack, ideal for VoIP engineers and enthusiasts. This guide covers the installation process on Linux and macOS, and provides a quick start on its usage. For Windows users, please refer to the detailed instructions provided in the official PJSIP documentation.
Once you can place calls from the terminal, pair it with sngrep to watch the SIP traffic, or with sipsak for quick OPTIONS checks.
Table of Contents
- Installing the PJSUA command line softphone on Linux
- Installing PJSUA on macOS
- Using the PJSUA command line
- Add custom headers to an outgoing INVITE
- Conclusion
Installing the PJSUA command line softphone on Linux
Install dependencies: Open a terminal and update your repositories. Then install the build packages:
apt-get updateapt install python-dev-is-python3 gcc make binutils build-essential
Get PJSIP: Download the PJSIP source code from GitHub. We will use the latest version, which is currently 2.17:
wget https://github.com/pjsip/pjproject/archive/refs/tags/2.17.tar.gztar xvf 2.17.tar.gzcd pjproject-2.17/
Configure and build PJSIP: Configure the environment and build:
export CFLAGS="$CFLAGS -fPIC"./configure && make dep && make
Install PJSUA: Copy the PJSUA binary to a directory in your PATH:
cp pjsip-apps/bin/pjsua* /usr/local/bin/pjsua
Verify installation: Check that PJSUA is installed:
pjsua --version
Installing PJSUA on macOS
On macOS, Homebrew does the whole job:
brew install pjproject
Using the PJSUA command line
Register a SIP account
Use the following command to register a SIP account:
pjsua --id="sip:USERNAME@DOMAIN" --registrar="sip:DOMAIN" --realm="*" --username="USERNAME" --password="PASSWORD"
Make a call
To make a call, press m and then press the enter key. Then enter the SIP URI in sip:number@host format and press enter again to place the call. Allow the request for microphone access to enable audio for the call.
Specify a protocol
The default protocol is UDP. To specify a different protocol, use the --use-tcp, --use-udp, or --use-tls flags. For TLS, you might need to specify the TLS certificate file and the TLS private key file if your setup requires them.
Receive a call without registration
To start PJSUA without registering to a SIP server, omit the registration parameters when launching it. You still need to specify your SIP URI with the --id option to identify yourself in calls:
pjsua --id="sip:user1@ip_address"
Make a call to this SIP URI and you will receive the call in the terminal.
Menu commands
The menu below shows how to use other features, like answering an inbound call or sending an UPDATE request.

Sample command:
pjsua --id="sip:test@1.2.3.4:5060" --registrar="sip:1.2.3.4:5060" --realm="*" --username="test" --password="password"
You can also make a call directly without registering first:
pjsua --id="sip:USERNAME@DOMAIN" --realm="*" --username="USERNAME" --password="PASSWORD" <SIP_URI>
Sample command:
pjsua --id="sip:akash@test.com" --username="akash" --password="password" --realm="*" sip:123456@test.com
Add custom headers to an outgoing INVITE
The PJSUA command line can add a custom SIP header without a custom build. Append the header to the destination SIP URI after ? as Header=Value. PJSIP turns each URI header parameter into a real header in the outgoing INVITE.
Keep the destination URI quoted so the shell does not treat ? and & as special characters:
pjsua \ --id="sip:akashtest@example.com" \ --proxy="sip:20.224.176.13:5060" \ "sip:4912345@initial.test.com?X-Test-ID=12345"
For multiple headers, separate each header parameter with &:
"sip:4912345@initial.test.com?X-Test-ID=12345&X-Customer-ID=abc"
I tested this with PJSUA 2.17 against a local UDP listener. Both headers arrive in the INVITE. The request URI and the To header stay clean:
INVITE sip:4912345@initial.test.com SIP/2.0To: sip:4912345@initial.test.comRoute: <sip:127.0.0.1:15070;lr>X-Test-ID: 12345X-Customer-ID: abc
Pro tip: URL-encode special characters in header values. For example, use %20 for a space. Then check the outgoing INVITE in the PJSUA log, or capture it with sngrep, to confirm every header is present.
To add headers from code instead, see the official guide on adding custom headers in PJSIP. For scripted SIP load and call-flow tests, SIPp is the next tool to learn.
Conclusion
The PJSUA command line offers a powerful and flexible way to work with SIP directly from your terminal. Whether you are a VoIP engineer or just starting out, PJSUA is an invaluable tool for testing, debugging, and managing SIP calls.
For more detailed information, visit the official PJSUA documentation.
Akash Gupta
Senior VoIP Engineer and AI Enthusiast

AI and VoIP Blog
Thank you for visiting the Blog. Hit the subscribe button to receive the next post right in your inbox. If you find this article helpful don’t forget to share your feedback in the comments and hit the like/clap button. This will helps in knowing what topics resonate with you, allowing me to create more that keeps you informed.
Thank you for reading, and stay tuned for more insights and guides!

Leave a Reply