Skip to main content

Getting Started with the CLI

The Svix CLI is one of the fastest ways to interact with our API, which is especially useful during development.

With the Svix CLI you can interact with our webhook sending API, validate webhook payloads, quickly open our docs, and much more.

In this tutorial, we will learn how to install the Svix CLI and use it to send your first webhook message!

info

This tutorial assumes you have already familiar with the Svix webhooks service. If this is your first time using Svix, we recommend you first check out our quickstart documentation.

Install the Svix CLI​

Before you go any further, you need to install the Svix CLI.

To install the Svix CLI with Homebrew, run:

brew install svix/svix/svix

Authenticate with your Svix account​

After installing the Svix CLI, you must authenticate with your Svix account before you can start running commands.

To do so, simply set your Svix Auth Token to the SVIX_AUTH_TOKEN env variable:

  • On macOS and Linux: export SVIX_AUTH_TOKEN=<MY-AUTH-TOKEN>
  • On Windows via command prompt: set SVIX_AUTH_TOKEN=<MY-AUTH-TOKEN>
  • On Windows via PowerShell: $env:SVIX_AUTH_TOKEN = '<MY-AUTH-TOKEN>'

Create an application​

You’re now ready to use the Svix CLI. To get started let's create a new application.

Each Svix CLI command accepts raw JSON input as either the first positional argument or piped via stdin.

We can create an application with the application create command:

svix application create '{"name": "My Application"}'

API commands also include convenience flags for common values to make it easier when handcrafting commands. For example, the same application could have been created using the --data-name flag: 

svix application create --data-name "My Application"

This command creates a new application on Svix and returns the raw application object as JSON.

List your applications​

Now that we've created an app we can list our existing apps with the following command:

svix application list

The list command by default returns the first 50 applications, you can change this limit by adding the --limit flag

# Get the first 100 applications
svix application list --limit 100

Add an endpoint​

Next let's add an endpoint to the application we created above. The create command should have returned an Application ID. Since the application name is not unique, we will need its ID to make changes.

Let's add a webhook endpoint with the url http://example.com/webhook. Every endpoint must have a version associated with it to help you version your webhook API. For this example we will set the version to 1.

svix endpoint create <MY-APP-ID> \
    --data-url http://example.com/webhook \
    --data-version 1

Send a message​

Now that we have an application created and an endpoint configured to listen to messages from that app, we are ready to send our first webhook message! Let's send a user.created event with the user's username and email.

svix message create <MY-APP-ID> \
    --data-eventType "user.created" \
    --data-payload '{
        "username": "new_user",
        "email": "new_user@example.com"
    }'

This message will now be sent to Svix and dispatched to all webhook endpoints listening to your application.

Get creative​

The Svix CLI has commands to interact with every part of the Svix API.

To get a complete list of commands, run svix --help.

Since each command accepts raw JSON input piped over stdin, you can chain Svix CLI commands together with other command line tools (like the popular JSON parser jq) to create powerful snippets to improve your workflow.

For example, to automatically open the dashboard for the app we created in step 3, on macOS you can run the following command:

svix application get <MY-APP-ID> | jq '.id' | xargs svix auth dashboard | jq '.url' | xargs open

With a slight modification, we can convert this one-liner to a shell function:

function dashboard {
   svix application get "$1" | jq '.id' | xargs svix auth dashboard | jq '.url' | xargs open
}

Which you can run like so:

dashboard <MY-APP-ID>