Classic Docs
Docs Navigation

Semaphore CLI: Overview

⛔️ Warning ⛔️: This guide is for Semaphore Classic, which has been superseded by Semaphore 2.0. For information on how to install the Semaphore 2.0 CLI, follow this guide instead.

The Semaphore Command Line Interface (CLI), is a tool named sem that can be used for creating and managing Semaphore projects from the command line / shell of various operating systems. It is built with Ruby and the code is open sourced.

If you have any problems or feature requests please open an issue in the CLI repository on GitHub.

  1. Prerequisites and installation
  2. Authentication
  3. Using the CLI
  4. Troubleshooting
  5. Remove Semaphore CLI from your system

# Prerequisites and installation

The Semaphore CLI requires Ruby >= 2.0 to run on your system. Before installation, verify that you have an up to date Ruby on your system.

$ ruby --version
ruby 2.0.0p648 (2015-12-16 revision 53162) [universal.x86_64-darwin16]

The Semaphore CLI is installed as a gem. Run the following command:

$ gem install sem

Verify that the installation succeded:

$ sem version

# Authentication

To manage resources on Semaphore, you need to log in to Semaphore from the command line:

$ sem login --auth-token <your-auth-token>

You can find your authentication token on the bottom of your user edit page.

To log out, execute the following:

$ sem logout

# Using the CLI

To explore the capabilities of the command line tool, start by running the help command that displays the list of available commands.

$ 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

To explore subcommands available in a namespace, run the help and pass it the name of the command you want to explore further.

$ sem help teams

Usage: sem teams:[command]

Manage teams and team membership

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

  teams:list                   List all your teams
  teams:info                   Show information about a team
  teams:create                 Create a new team
  teams:rename                 Change the name of the team
  teams:set-permission         Set the permission level of the team
  teams:delete                 Removes a team from your organization

  teams:members:list           List members of the team
  teams:members:add            Add a user to the team
  teams:members:remove         Remove a user from the team

  teams:projects:list          List projects in a team
  teams:projects:add           Add a project to a team
  teams:projects:remove        Remove a project from the team

  teams:secrets:list           List secrets in a team
  teams:secrets:add            Add a secret to a team
  teams:secrets:remove         Removes a secret from the team

To get a help for a specific command, run the help command and pass in the name of the command:

$ sem help teams:create

Usage: sem teams:create [TEAM_NAME] [FLAGS]

Create a new team

  --permission PERMISSION  Permission level of the team in the organization


    $ sem teams:create renderedtext/interns
    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

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

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

The help command will always display an example use case of the command.

# Troubleshooting

The Semaphore CLI can display all the API requests that can help with identifying issues. This mode is called trace mode.

To run the CLI in trace mode, pass the --trace flag to the CLI:

$ sem orgs:list --trace

I, [2017-10-19T17:01:26.406390 #20526]  INFO -- : get
I, [2017-10-19T17:01:27.297507 #20526]  INFO -- Status: 200
D, [2017-10-19T17:01:27.297583 #20526] DEBUG -- response: [{"id":"76b2b973-a07c-4336-af1c-b10c6bf1f6d5","name":"renderedtext","username":"renderedtext","url":"","projects_url":"","users_url":"","teams_url":"","shared_configs_url":"","created_at":"2017-02-07T17:13:14+01:00","updated_at":"2017-03-09T08:00:31+01:00"}]

ID                                    NAME
76b2b973-a07c-4336-af1c-b10c6bf1f6d5  renderedtext

# Remove Semaphore CLI from your system

To remove the Semaphore CLI from your system, run the following command:

$ gem uninstall sem

Semaphore Docs are open source — Edit on GitHub


Occasional lightweight product and blog updates. Unsubscribe at any time.

2009-2019 © Rendered Text. All rights reserved. Terms of Service, Privacy policy, Security.