23 Apr 2020 · Software Engineering

    Semaphore CLI: Forming a Base for a Programmable Semaphore

    3 min read

    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!

    Leave a Reply

    Your email address will not be published. Required fields are marked *

    Writen by:
    Chief Architect at Semaphore. A decade of experience in dev productivity, helping close to 50,000 organizations with operational excellence.