Our new ebook “CI/CD with Docker & Kubernetes” is out. Download it here.

Semaphore CLI: Forming a Base for a Programmable Semaphore

Being able to control your CI pipeline programmatically, tweak and bend it to your will, is a huge benefit for both small and large organizations. This is why we have deprecated our old API v1 and introduced a new API v2, and this is why we are now introducing a command-line utility.

The Semaphore Command Line Interface (CLI), is a tool for creating and managing Semaphore projects from the command line.

Same as with our API v2 and Test Boosters, the Semaphore CLI is open sourced. We believe in the power of the community and want to promote full transparency when it comes to installing custom software on your machines.

Features offered by the Semaphore CLI

The Semaphore CLI is Ruby gem, so if you have an up-to-date Ruby version on your machine (Ruby >= 2.0), you can install it with the following command:

$ gem install sem

Next, log into Semaphore (you can find your auth-token at the bottom of the users edit page):

$ sem login --auth-token 

Now, you are free to explore the features offered by the command line interface.

$ sem help

Usage: sem [command]

Command list, type sem help [command] for more details:

  version         Check cli version
  login           Log in to semaphore from the command line
  logout          Log out from semaphore

  orgs            Manage organizations
  teams           Manage teams and team membership
  secrets         Manage secrets
  projects        Manage projects

Currently, you can manage four types of resources on Semaphore:

Exploring the Semaphore CLI

Let’s explore some commands. For example, team managment.

# Listing our teams

$ sem teams:list
ID                                    NAME                 PERMISSION  MEMBERS
1bc7ed43-ac8a-487e-b488-c38bc757a034  renderedtext/devs    write       2 members
1bc7ed43-ac8a-487e-b488-c38bc757a034  renderedtext/admins  write       0 members

# Creating a new team

$ sem teams:create renderedtext/interns --permission read
ID          1bc7ed43-ac8a-487e-b488-c38bc757a034
Name        renderedtext/interns
Permission  read
Members     0 members
Created     2017-08-01 13:14:40 +0200
Updated     2017-08-02 13:14:40 +0200

# Adding users to our teams

$ sem teams:members:add renderedtext/interns shiroyasha
User shiroyasha added to the team.

As you can observe in the the above output, the command line expects the
/ (e.g renderedtext/admins) format to
identify your resources.

How to get started with Semaphore CLI

Our Semaphore CLI documentation covers the usage of every command in the CLI, the installation process, authentication, and includes a troubleshooting sections for common issues.

The source code of the Semaphore CLI is open sourced, and can offer additional insights into the inner cogs of the gem.

If you notice any issues with the CLI, please open an issue on GitHub.

We are looking forward to your feedback

Is there a feature you would like to see as part of our new CLI? Please open an issue in the CLI repository on GitHub. We’re looking forward to reading your feedback.

Head over to the Semaphore CLI Overview Page to install and test out our new CLI.

Happy building!

Related reads:

Have a comment? Join discussions on our forum.
Post a comment

Sign up for a weekly Semaphore newsletter