Introducing the Split CLI

Hey developers! Interested in creating and managing your splits and segments directly from the command line? We get it… We’re pretty proud of our UI, but we value developer efficiency and we want to make sure you can work with Split in ways that work with your existing style. So, today we’re introducing the Split Command Line Interface (CLI) – made by developers for developers! Using the CLI tool, you can go from setting up your Split account to creating and ramping your feature flag in minutes.

Set Up the Split CLI

The Split CLI runs on macOS, Linux, and Windows. You need to have Python 3.6 or higher installed on your machine.

The simplicity of the Split CLI lets you get started with the entire feature flag lifecycle in under 5 minutes! To install the CLI, enter pip install splitcli in your terminal. Once that’s finished, run the CLI with splitcli. If you are new to Split, you have the option to create an account. You will be prompted to enter your first name, last name, email address, and phone number. You will then receive a 6 digit one-time password to authenticate.

If you already have an existing Split account, select Yes, take me to sign in from the initial prompt. You will then enter your email address, followed by your Admin API Key, which can be found in the Admin Settings of your Split profile.

Need to find your Admin API key? We’ve got a video for you!.

Manage Your Feature Flag Life Cycle with the Split CLI

From the Main Menu, you have four options: Manage Splits, Manage Segments, Manage Metrics, and Manage Organizations.

Today, you can manage the entire lifecycle of a Split through the CLI – from testing in production, to your first ramps and measurement, and on to a final decision! Let’s try it out!


The first thing you need to do to get started with testing in production is create a segment, which is just a group of users that you can use to target in my feature flags.

From Manage Segments, select Create a new Segment, and call this Beta Testers. Through the CLI, you can add users one at a time to this segmented user base, or you can do it in bulk by uploading a CSV. This list can start with the development team and expand to QA and even beta customers through the testing process.

Manage Splits

Back at the main menu, you can now Manage Splits, where you see all of the splits that are already in your organization as well as the option to create a new Split. When you select Create a new split, you will be prompted to enter a name and a description. Then, you choose whether you want a simple rollout, which gives you the ability to turn a feature on or off in any environment, or a custom set of treatments.

Choose a simple rollout. You then need to choose the environment to manage your split in. Let’s choose production, because after all, we are testing in production!

Before you add any configurations to your split, let’s look at the current JSON definition.

{ "name": "split_1234", "environment": { "id": "f8aa2660-3f31-11eb-be37-12b057418355", "name": "Prod-Default" }, "trafficType": { "id": "f8a8ede0-3f31-11eb-be37-12b057418355", "name": "user" }, "killed": false, "treatments": [ { "name": "on" }, { "name": "off" } ], "defaultTreatment": "off", "baselineTreatment": "off", "trafficAllocation": 100, "rules": [], "defaultRule": [ { "treatment": "off", "size": 100 } ], "creationTime": 1615492168464, "lastUpdateTime": 1615492168464 }
Code language: JSON / JSON with Comments (json)

Here you see that the default rule is 100% off, and there are no targeted users. You want to target your Beta Testers so they can get started with testing. To turn this flag on in production for only beta testers, select Target segments, select the treatment you want to target – so ON in this case – then add the Beta Testers segment by hitting the Spacebar, and then Enter.

Now, when you show definition, you can see that the treatment is on for your beta testers, but off for everyone else.

{ "name": "split_1234", "environment": { "id": "f8aa2660-3f31-11eb-be37-12b057418355", "name": "Prod-Default" }, "trafficType": { "id": "f8a8ede0-3f31-11eb-be37-12b057418355", "name": "user" }, "killed": false, "treatments": [ { "name": "on", "segments": [ "Beta_Testers" ] }, { "name": "off" } ], } Targeting 'on' to segments: Beta_Testers Default Rule: 100% off
Code language: PHP (php)

When any of the beta testers visit the product, they will have access to this new feature, while the rest of your users do not. Easy, right?!

Keep Ramping

Once you have tested the feature in production, and it looks good, you can start incrementally rolling your feature out. To do that, select Ramp Split again, and enter the percentage of your user base that you will scale this new feature to. Try a small percentage initially, like 5.

{ "name": "split_1234", "environment": { "id": "f8aa2660-3f31-11eb-be37-12b057418355", "name": "Prod-Default" }, "trafficType": { "id": "f8a8ede0-3f31-11eb-be37-12b057418355", "name": "user" }, "defaultRule": [ { "treatment": "on", "size": 5 }, { "treatment": "off", "size": 95 } ], "creationTime": 1615492168464, "lastUpdateTime": 1615492645545 } Targeting 'on' to segments: Beta_Testers Default Rule: 5% on, 95% off
Code language: C# (cs)

When you look at the definition, you can see that the feature is on for 5% of you users and off for 95%. Amazing!

Kill Switch

Now, let’s say Split’s alerting identifies a bug in your feature. Rather than expose more customers, you can turn the release off while your team investigates the issue. From the Manage Splits menu, select Kill for the split you wish to kill, and you can see that the feature has instantly been killed in production.

You killed split_1234 in Prod-Default. RIP.

Now you can go figure out what is causing the production issue, deploy a fix, and when it’s ready again, go back into the Manage Splits menu, and select Restore for the split you wish to restore.

You restored split_1234 in Prod-Default. It's Alive!!

Ramp Split

Now that you’ve tested and fixed, your confidence in your new feature has increased. Now it’s time to roll your new feature out to 100% of your user base with the Ramp split functionality of the CLI!

After the rollout is complete, you don’t need the old behavior anymore, so you can delete the split. You don’t want stale feature flags taking up space in your environments. In your code, remove the if else statement. Then, select the split you wish to delete from the Manage Splits menu, and choose Delete Split.

Contribute to the CLI

Because the CLI is open source, we want to open it up to all of you to contribute! From the repo, you can open PRs and flag any issues that arise. If you love our work, we’d love it if you’d give us a star!

Build Smarter with Split

This is only a fraction of all that the Split CLI can do. It is another tool that developers can use to build and learn faster, and we are so excited to see what you all do with it! To build your apps smarter with Split, check out these other tutorials, and be sure to follow us on Twitter and subscribe to our YouTube channel!