

sem CLI Reference#

sem, the Semaphore Command Line Interface (CLI), makes it easy to create and manage your Semaphore projects and resources directly from the terminal. It’s an essential part of using Semaphore.

Download and install#

To download and install sem, copy and paste the installation command:

curl https://storage.googleapis.com/sem-cli-releases/get.sh | bash

Next, you'll need to connect sem to an organization. The command includes the URL and access token. In your web browser you'll see something similar to:

sem connect ORGANIZATION.semaphoreci.com ACCESS_TOKEN

You can find the exact sem connect command, which includes your current organization name and access token, by invoking the CLI widget in the top-right corner of any screen on Semaphore.

Your access token is also always available, and revokable, on your account page.

Overview#

Syntax#

The general syntax of the sem utility is as follows:

sem [COMMAND] [RESOURCE] [NAME] [flags]

where [COMMAND] is the name of the command as explained in this reference page, [RESOURCE] is the resource type that interests us, [NAME] is the actual name of the resource and [flags] are optional command line flags.

Not all sem commands require a [RESOURCE] value and most sem commands do not have a [flag] part.

Some of the [flags] values need an additional argument, as it is the case with the -f flag, which requires a valid path to a local file.

Operations#

The following list briefly describes all sem operations:

connect: The connect command is used for connecting to an organization for the first time.
context: The context command is used for switching organizations.
create: The create command is used for creating new resources.
delete: The delete command is used for deleting existing resources.
get: The get command is used for getting a list of items for an existing type of resource as well as getting analytic information about specific resources.
edit: The edit command is used for editing existing projects, secrets, notifications and dashboards using your configured text editor.
apply: The apply command is used for updating existing secrets and dashborads using a secret or a dashaboard YAML file and requires the use of the -f flag.
attach: The attach command is used for attaching to a running job.
debug: the debug command is used for debugging jobs and projects.
logs: The logs command is used for getting the logs of a job.
stop: The stop command is used for stopping pipelines, workflows and jobs from running.
rebuild: The rebuild command is used for rebuilding workflows and pipelines
port-forward: The port-forward command is used for redirecting the network traffic from a job that is running in the VM to your local machine.
help: The help command is used for getting help about sem or an existing sem command.
init: The init command is used for adding an existing GitHub repository to Semaphore 2.0 for the first time and creating a new project.
version: The version command is used for getting the version of the sem utility.

Resource types#

You can use sem to manipulate five types of Semaphore resources: dashboards, jobs, notifications, projects, pipelines, workflows and secrets. Most resource related operations require either a valid resource name or an ID.

Dashboards#

A Semaphore 2.0 dashboard is a place when you can keep the widgets that you define in order to overview the operations of your current Semaphore 2.0 organization.

A widget is used for following the activity of pipelines and workflows according to certain criteria that are defined using filters that help you narrow down the displayed information.

As it happens with secrets, each dashboard is associated with a given organization. Therefore, in order to view a specific dashboard you should be connected to the organization the dashboard belongs to.

Jobs#

A job is the only Semaphore 2.0 entity that can be executed in a Virtual Machine (VM). You cannot have a pipeline without at least one job.

The jobs of a Semaphore 2.0 pipelines are independent from each other as they are running in completely different Virtual Machines.

Notifications#

A notification offers a way for sending messages to one or more Slack channels or users. Notifications are delivered on the success or failure of a pipeline. Notification rules contain user-defined criteria and filters.

A notification can contain multiple rules that are being evaluated each time a pipeline ends, either successfully or unsuccessfully.

Projects#

A project is the way Semaphore 2.0 organizes, stores and processes GitHub repositories. As a result each Semaphore 2.0 project has a direct relationship with a single GitHub repository.

However, the same GitHub repository can be assigned to multiple Semaphore 2.0 projects under different names. Additionally, the same project name can exist under multiple Semaphore 2.0 organizations and deleting a Semaphore 2.0 project from an organization will not automatically delete that project from the other organizations that project exists in. Last, the related GitHub repository will remain intact after deleting a project from Semaphore 2.0.

You can use the same project name in multiple organizations but you cannot use the same project name more than once under the same organization.

Pipelines#

The smallest unit of scheduling and execution in Semaphore 2.0 is the Job. A pipeline is the Semaphore 2.0 entity where jobs are defined in order to get executed in a Virtual Machine.

Each pipeline is defined using a YAML file. The YAML file of the initial pipeline is .semaphore/semaphore.yml. This value can be adjusted by editing the project configuration.

Workflows#

Put simply, a workflow is the execution of a Semaphore 2.0 project. Each workflow has its own Workflow ID that uniquely differentiates each workflow execution from the other workflow executions.

A workflow is composed of one or more pipelines depending on whether there exist promotions or auto promotions in the workflow. Therefore, a workflow should be viewed of as a group of pipelines or, if you like strict definitions, as a dynamically configurable, n-ary tree of pipelines.

Secrets#

A secret is a bucket for keeping sensitive information in the form of environment variables and small files. Therefore, you can consider a secret as a place where you can store small amounts of sensitive data such as passwords, tokens or keys. Sharing sensitive data in a secret is both safer and more flexible than storing it using plain text files or environment variables that anyone can access.

Each secret is associated with a single organization. In other words, a secret belongs to an organization. In order to use a specific secret you should be connected to the organization that owns it.

Working with organizations#

This group of sem commands for working with organizations contains the sem connect and sem context commands.

sem connect#

The sem connect command allows you to connect to a Semaphore 2.0 organization for the first time and requires two command line arguments. The first command line argument is the organization domain and the second command line argument is the user authentication token – the organization must already exist.

The sem connect command checks whether the user entered the correct authentication token or not. If the authentication token is correct, it is stored on the current computer. If the authentication token is incorrect, then it is not stored on the current computer.

Organizations are created using the web interface of Semaphore 2.0.

The authentication token depends on the active user.

Once you connect to an organization, you do not need to execute sem connect for connecting to that organization again – you can connect to any organization that you are already a member of using the sem context command.

sem connect example#

The sem connect command should be executed as follows:

sem connect tsoukalos.semaphoreci.com NeUFkim46BCdpqCAyWXN

sem context#

The sem context command is used for listing the organizations the active Semaphore 2.0 user belongs to and for changing between organizations.

The sem context command can be used with or without any command line parameters. If sem context is used without any other command line parameters, it returns the list of Semaphore 2.0 organizations the active user has previously connected to with the sem utility. When used with a command line argument, which should be a valid organization name the active user belongs to, sem context will change the active organization to the given one.

sem context example#

The next command will just list all the organizations the connected user belongs to:

sem context

In the output of sem context, the active organization will have a - character in front of it.

If you use an argument with sem context, then that argument should be a valid organization name as it appears in the output of sem context. So, in order to change from the current organization to tsoukalos_semaphoreci_com, you should execute the next command:

sem context tsoukalos_semaphoreci_com

Working with resources#

This group of sem commands includes the five most commonly and frequently used commands: sem create, sem delete, sem edit, sem apply and sem get. This mainly happens because these are the commands that allow you to work with resources.

sem create#

The sem create command is used for creating new resources and can be followed by the -f flag, which should be followed by a valid path to a proper YAML file. Currently there exist four types of YAML resource files that can be handled by sem create: secrets, dashboards, jobs and projects resource files.

However, for secrets and dashboards only, you can use sem create to create an empty secret or dashbord without the need for a YAML file as follows:

sem create secret [name]
sem create dashbord [name]

Should you wish to learn more about creating new resources, you can visit the Secrets YAML reference, the Dashboard YAML reference, the Jobs YAML reference and the Projects YAML reference pages of the Semaphore 2.0 documentation.

sem create examples#

If you have a valid secret, dashboard or project YAML file stored at /tmp/valid.yaml, you should execute the next command in order to add that secret, dashboard or project under the current organization:

sem create -f /tmp/valid.yaml

Additionally, the following command will create a new and empty secret that will be called my-new-secret:

sem create secret my-new-secret

Last, the following command will create a new and empty dashboard that will be called my-dashboard:

sem create dashboard my-dashboard

You cannot execute sem create project [name] in order to create an empty Semaphore 2.0 project.

sem create secret with environment variables and files#

To create a secret with a list of environment variables and files, you can pass them during creation.

For example to create a secret example-secret with two environment variables and a file, use:

sem create secret example-secret \
  -e FOO=BAR \
  -e "MESSAGE=Hello World" \
  -f /Users/John/hello.txt:/home/semaphore/hello.txt

Use the -f or --file flag to specify one or more files. The format of the parameter is <local-path>:<path-on-sempahore>. If the <path-on-semaphore> is an absolute path, for example /etc/hosts it will be mounted to /etc/hosts. If the <path-on-semaphore> is a relative path, for example .ssh/id_rsa_test it will be mounted relative to the home directory, in this example /home/semaphore/.ssh/id_rsa_test.

Use the -e or --env flag to specify one or more environment variables. The format of the parameter is <NAME>=<VALUE>.

sem edit#

The sem edit command works for projects, secrets, notifications and dashboards and allows you to edit the YAML representation of these resources using your configured text editor.

The sem edit command does not support the job resource type.

sem edit examples#

The following command will edit an existing secret that is named my-secret and will automatically run your configured text editor:

sem edit secret my-secret

What you are going to see on your screen is the YAML representation of the my-secret secret.

Similarly, the next command will edit a dashboard named my-activity:

sem edit dashboard my-activity

To edit a project with the name my-project, use the following command:

sem edit project my-project

sem get#

The sem get command can do two things. First, it can return a list of items for the given resource type that can be found in the active organization. This option requires a command line argument, which is the resource type. Second, it can return analytical information for an existing resource. In this case you should provide sem get with the type of the resource and the name of the resource that interests you, in that exact order.

In the first case, sem get can be used as follows:

sem get [RESOURCE]

In the second case, sem get should be used as follows:

sem get [RESOURCE] [name]

In the case of a job resource, you should give the Job ID of the job that interests you and not its name.

sem get examples#

As the sem get command works with resources, you will need to specify a resource type when issuing a sem get command all the time.

So, in order to get the list of the available projects for the current user under the active organization, you should execute the following command:

sem get project

Similarly, the next command returns the list of the names of the available secrets for the current user under the active organization:

sem get secret

Each entry is printed on a separate line, which makes the generated output suitable for being further processed by traditional UNIX command line tools.

Additionally, you can use sem get to display all running jobs:

sem get jobs

Last, you can use sem get jobs with --all to display the more recent jobs of the current organization, both running and finished:

sem get jobs --all

In order to find out more information about a specific project named docs, you should execute the next command:

sem get project docs

Similarly, in order to find out the contents of a secret named mySecrets, you should execute the next command:

sem get secret mySecrets

You can also use sem get for displaying information about a dashboard:

sem get dashboard my-dashboard

In order to find more information about a specific job, given its Job ID, either running or finished, you should execute the next command:

sem get job 5c011197-2bd2-4c82-bf4d-f0edd9e69f40

sem apply#

The sem apply command works for secrets and dashboards and allows you to update the contents of an existing secret or dashboard using an external secrets or dashboards YAML file. sem apply is used with the -f command line option followed by a valid path to a proper YAML file.

sem apply example#

The following command will update the my-secret secret according to the contents of the aFile, which should be a valid secrets YAML file:

sem apply -f aFile

If everything is OK with aFile, the output of the previous command will be as follows:

Secret 'my-secrets' updated.

This means that the my-secrets secret was updated successfully.

You can also use sem apply -f in a similar way to update an existing dashboard.

sem delete#

The sem delete command is used for deleting existing resources, which means that is used for deleting Semaphore 2.0 projects, dashboards and secrets.

When you delete a secret, then that particular secret will disappear from the active organization, which will affect all the Semaphore 2.0 projects that are using it.

When you use sem delete to delete a project then that particular project is deleted from the active organization of the active user.

Deleting a dashboard does not affect any Semaphore 2.0 projects.

sem delete example#

In order to delete an existing project named be-careful from the current organization, you should execute the next command:

sem delete project be-careful

Similarly, you can delete an existing dashboard named my-dashboard as follows:

sem delete dashboard my-dashboard

Last, you can delete an existing secret named my-secret as follows:

sem delete secret my-secret

The sem delete command does not work with jobs.

Working with jobs#

The list of commands for working with jobs includes the sem attach, sem logs, sem port-forward and sem debug commands. You can also use sem create -f to create a one-off job that is not part of a pipeline.

Additionally, you can use the the sem get command for getting a list of all jobs or getting a description for a particular job.

The sem get jobs command returns the list of all running jobs.

The sem get jobs --all command returns the list of all recent jobs of the current organization, both running and finished.

The sem stop command allows you to stop a running job or entire pipeline.

Creating one-off jobs#

You can use sem create -f to create a one-off job that runs without being part of an existing pipeline. You will need to provide sem create -f a valid YAML file as described in the Jobs YAML Reference page.

This can be very useful for checking out things like compiler versions and package availability before adding a command into a bigger and slower pipeline.

When a job is created this way, it cannot be viewed in the UI of Semaphore 2.0. The only way to see the results of such a job is with the sem logs command.

One-off job creation example#

sem create -f /tmp/aJob.yml

The aforementioned command creates a new job based on the contents of /tmp/aJob.yml, which are as follows:

apiVersion: v1alpha
kind: Job
metadata:
  name: A new job
spec:
  files: []
  envvars: []
  secrets: []
  commands:
    - go version
  project_id: 7384612f-e22f-4710-9f0f-5dcce85ba44b

The value of project_id must be valid or the sem create -f command will fail.

The output of the sem create -f command looks as follows:

Job '686b3ed4-be56-4e95-beee-b3bbcc3981b3' created.

sem attach#

The sem attach allows you to connect to running jobs with an interactive SSH session. This allows you to explore and inspect the state of jobs.

When the job ends, the SSH session will automatically end and the SSH connection will be closed.

If you want to debug finished jobs, use sem debug jobs [job-id] instead.

sem attach example#

The sem attach command requires the Job ID of a running job as its single parameter. So, the following command will connect to the environment of the job with Job ID 6ed18e81-0541-4873-93e3-61025af0363b using SSH:

sem attach 6ed18e81-0541-4873-93e3-61025af0363b

The job with the given Job ID must be in running state at the time of execution of sem attach.

sem logs#

The sem logs command allows you to see the log entries of a job, which is specified by its Job ID.

The sem logs command works with both finished and running jobs.

sem logs example#

The sem logs command requires the Job ID of a job as its parameter:

sem logs 6ed18e81-0541-4873-93e3-61025af0363b

The last lines of the output of the previous command of a PASSED job should be similar to the following output:

✻ export SEMAPHORE_JOB_RESULT=passed
exit status: 0
Job passed.
````

### sem port-forward

The general form of the `sem port-forward` command is the following:

``` bash
sem port-forward [JOB ID of running job] [LOCAL TCP PORT] [REMOTE TCP PORT]

So, the sem port-forward command needs three command line arguments: the Job ID, the local TCP port number that will be used in the local machine, and the remote TCP port number, which is defined in the Virtual Machine (VM).

The sem port-forward command works with running jobs only.

sem port-forward example#

The sem port-forward command is executed as follows:

sem port-forward 6ed18e81-0541-4873-93e3-61025af0363b 8000 8080

The previous command tells sem to forward the network traffic from the TCP port 8000 of the job with job ID 6ed18e81-0541-4873-93e3-61025af0363b that is running in a VM to TCP port 8080 of your local machine.

All traffic of sem port-forward is transferred over an encrypted SSH channel.

Note: Port-Forwarding works only for Virtual Machine based CI/CD environments.

sem debug for jobs#

The general form of the sem debug command for jobs is the following:

sem debug job [Job ID]

This will start a new interactive job based on the specification of the old one, export the same environment variables, inject the same secrets, and connect to the same git commit.

Commands in the debug mode are not executed automatically, instead they are stored in ~/commands.sh. This allows you to execute them step-by-step, and inspect the changes in the environment.

By default, the duration of the SSH session is limited to one hour. To run longer debug sessions, pass the duration flag to the above command:

sem debug job [job-id] --duration 3h

A debug session does not include the contents of the GitHub repository related to your Semaphore 2.0 project. Run checkout in the debug session to clone your repository.

The --duration flag#

By default the SSH session of a sem debug command is limited to one hour. In order to change that, you can pass the --duration flag to the sem debug command.

You can define the time duration using numeric values in the XXhYYmZZs format using any valid combination. One hour can be defined as 1h0m0s or just 1h or even as 60m.

sem stop#

You can stop a running job or pipeline with sem stop:

sem stop job|pipeline [ID]

If you are executing sem stop job, you will need to provide an ID of a running job. If you are executing sem stop pipeline, you will need to provide an ID of a running pipeline.

sem stop example#

The following command will stop the job with a Job ID of 0ae14ece-17b1-428d-99bd-5ec6b04494e9:

sem stop job 0ae14ece-17b1-428d-99bd-5ec6b04494e9

The following command will stop the pipeline with a Pipeline ID of ea3e6bba-d19a-45d7-86a0-e78a2301b616:

sem stop pipeline ea3e6bba-d19a-45d7-86a0-e78a2301b616

Working with projects#

This group includes the sem init, sem edit and sem debug commands.

sem init#

The sem init command adds a GitHub repository as a Semaphore 2.0 project to the active organization.

The sem init command should be executed from within the root directory of the GitHub repository that has been either created locally and pushed to GitHub or cloned using the git clone command. Although the command can be executed without any other command line parameters or arguments, it also supports the --project-name and --repo-url options.

--project-name#

The --project-name command line option is used for manually setting the name of the Semaphore 2.0 project.

--repo-url#

The --repo-url command line option allows you to manually specify the URL of the GitHub repository in case sem init has difficulties finding that out.

sem init example#

As sem init can be used without any command line arguments, you can execute it as follows from the root directory of a GitHub repository that resides on your local machine:

sem init

If a .semaphore/semaphore.yml file already exists in the root directory of a GitHub repository, sem init will keep that .semaphore/semaphore.yml file and continue its operation. If there is no .semaphore/semaphore.yml file, sem init will create one.

If you decide to use --project-name, then you can call sem init as follows:

sem init --project-name my-own-name

The previous command creates a new Semaphore 2.0 project that will be called my-own-name.

Using --repo-url with sem init is much trickier because you should know what you are doing.

Troubleshooting#

In case running sem init returns an error:

error: http status 422 with message
"{"message":"POST https://api.github.com/repos/orgname/projectname/keys: 404 - Not Found // See:
https://developer.github.com/v3/repos/keys/#add-a-new-deploy-key";}"
received from upstream

or

"{"message":"admin permisssions are required on the repository in order to add the project to Semaphore"}"

or

error: http status 422 with message "{"message":"Repository 'orgname/projectname' not found"}"
received from upstream

You can do the following:

Check if the user who wants to add a project to Semaphore is a member of the given Semaphore organization, and has Admin-level permissions for the repository on GitHub.
Check if the access for Semaphore 2.0 was granted within your GitHub organization. You can do that on GitHub.
Request the GitHub organization owner to give access to Semaphore. Refer to GitHub documentation for details.

sem edit#

You can edit a project by using the sem edit project command, followed by the name of an existing project.

sem edit project [name]

The sem edit project command will start your configured text editor. In order for the changes to take effect, you will have to save the changes and exit your text editor.

To learn more about the configuration options for projects, visit the Projects YAML Reference.

sem debug for projects#

You can use the sem debug command to debug an existing Semaphore 2.0 project.

The sem debug command can help you specify the commands of a job before adding and executing it in a pipeline. This can be particularly helpful when you do not know whether the Virtual Machine you are using has the latest version of a programming language or a package and when you want to know what you need to download in order to perform the task you want.

The general form of the sem debug project command is the following:

sem debug project [Project NAME]

After that you are going to get automatically connected to the VM of the project using SSH. The value of SEMAPHORE_GIT_BRANCH will be master whereas the value of SEMAPHORE_GIT_SHA will be HEAD, which means that you will be using the latest version of the master branch available on the GitHub repository of the Semaphore 2.0 project.

The projects that are created using the sem debug project command support the --duration parameter for specifying the timeout period of the project.

sem debug project example#

You can debug a project named docker-push by executing the following command:

sem debug project docker-push

You will need to execute either sudo poweroff or sudo shutdown -r now to manually terminate the VM. Otherwise, you can wait for the timeout period to pass.

By default the SSH session of a sem debug command is limited to one hour. In order to change that, you can pass the --duration flag to the sem debug command.

You can define the time duration using numeric values in the XXhYYmZZs format using any valid combination. One hour can be defined as 1h0m0s or just 1h or even as 60m.

The next command specifies that the SSH session for the deployment project will time out in 2 minutes:

sem debug project deployment --duration 2m

The next command specifies that the SSH session for the job with JOB ID d7caf99e-de65-4dbb-ad63-91829bc8a693 will time out in 2 hours:

sem debug job d7caf99e-de65-4dbb-ad63-91829bc8a693 --duration 2h

Last, the following command specifies that the SSH session of the deployment project will time out in 20 minutes and 10 seconds:

sem debug project deployment --duration 20m10s

Changing the initial pipeline file#

By default, .semaphore/semaphore.yml is the initial pipeline file that is triggered when a git hook is received on Semaphore.

To modify the initial pipeline file, edit the repository section in the project YAML.

For example, to modify the initial pipeline file from .semaphore/semaphore.yml to .semaphore/alternative-tests.yml edit your project with the following command:

sem edit project example-project-1

In the editor, modify the pipeline_file entry:

# Editing Projects/example-project-1.

apiVersion: v1alpha
kind: Project
metadata:
  name: example-project-1
  id: 37db0a22-592c-45e2-bdeb-799ba977502c
  description: "Example project"
spec:
  repository:
    url: git@github.com:example/project-1.git
    run_on:
      - tags
      - branches

    #
    # Edit this line to set a new entry-point YAML file for the project.
    #
    pipeline_file: ".semaphore/alternative-tests.yml"

When you save the changes and leave the editor, your changes will be applied to the project.

Changing GitHub status check notifications#

By default, Semaphore will submit pull request status checks for the initial pipeline.

To change this, edit the status property in the repository section of project YAML.

Add status notifications from promoted pipelines#

Let's say that your Semaphore workflow is composed of two pipelines: a promotion connects semaphore.yml to production.yml.

To submit status checks from the pipeline defined in production.yml, modify the pipeline_files entry and add an additional pipeline file:

# Editing Projects/example-project-1.

apiVersion: v1alpha
kind: Project
metadata:
  name: example-project-1
  id: 37db0a22-592c-45e2-bdeb-799ba977502c
  description: "Example project"
spec:
  repository:
    url: git@github.com:example/project-1.git
    run_on:
      - tags
      - branches
    pipeline_file: ".semaphore/semaphore.yml"
    status:
      pipeline_files:
      - path: ".semaphore/semaphore.yml"
        level: "pipeline"
        #
        # Add this line to send status also after promotion
        #
      - path: ".semaphore/production.yml"
        level: "pipeline"

Pipeline or block level statuses#

Status notifications can be set on two levels: pipeline or block.

pipeline level means that only one GitHub status will be created per commit. The name of the status is based on name of the pipeline.

block level means that Semaphore will create a status for each block in the pipeline. The name of each status is based on the corresponding block name.

Working with notifications#

In this section you will learn how to work with notifications with the sem utility starting with how to create a new notification with a single rule.

Create a notification#

The first thing that you will need to do is to create one or more notifications with the help of the sem utility.

The general form of the sem create notification command is as follows:

sem create notification [name] \
  --projects [list of projects] \
  --branches [list of branches] \
  --slack-endpoint [slack-webhook-endpoint] \
  --slack-channels [list of slack channels] \
  --pipelines [list of pipelines]

Please refer to the Examples section to learn more about the use of the sem create notification command.

You do not need to use all the command line options of the sem create notification command when creating a new notification. However, the --projects as well as the --slack-endpoint options are mandatory. The former specifies the list of Semaphore 2.0 projects that will be included in that notification rule and the latter specifies the URL for the Incoming WebHook that will be associated with this particular notification rule. All --branches, --pipelines and --slack-channels are optional.

If the --slack-channels option is not set, the default Slack channel that is associated with the specified Incoming WebHook will be used. If you want to test your notifications, you might need to create a dedicated Slack channel for that purpose.

Additionally, the values of --branches, --projects and --pipelines can contain regular expressions. Regex matches must be wrapped in forward slashes (/.-/). Specifying a branch name without slashes (example: .-) would execute a direct equality match.

Therefore, the minimum valid sem create notification command that can be executed will have the following form:

sem create notification [name] \
  --projects [list of projects] \
  --slack-endpoint [slack-webhook-endpoint]

The sem create notification command can only create a single rule under the newly created notification. However, you can now use the sem edit notification command to add as many rules as you like to the specified notification.

Tip: you can use just a single Incoming WebHook from Slack for all your notifications as this Incoming WebHook has access to all the channels of a Slack Workspace.

List notifications#

You can list all the available notifications under the current organization with the sem get notifications command.

sem get notifications

Describe a notification#

You can describe a notification using the sem get notifications command followed by the name of the desired notification.

sem get notifications [name]

The output of the previous command will be a YAML file – you can learn more about the Notifications YAML grammar by visiting the Notifications YAML reference.

Edit a notification#

You can edit a notification using the sem edit notification command followed by the name of the existing notification.

sem edit notification [name]

The sem edit notification command will start your configured text editor. In order for the changes to take effect, you will have to save the changes and exit your text editor.

Delete a notification#

You can delete an existing notification using the sem delete notification command followed by the name of the notification you want to delete.

sem delete notifications [name]

Working with notifications examples#

In this subsection you will find sem examples related to notifications.

You can create a new notification named documents as follows:

sem create notifications documents \
  --projects "/.*-api$/" \
  --branches "master" \
  --pipelines "semaphore.yml" \
  --slack-endpoint https://hooks.slack.com/services/XXTXXSSA/ABCDDAS/XZYZWAFDFD \
  --slack-channels "#dev-team,@mtsoukalos"

You can list all existing notifications under the current organization as follows:

sem get notifications

The output that you will get from the previous command will look similar to the following:

$ sem get notifications
NAME        AGE
documents   18h
master      17h

The AGE column shows the time since the last change.

You can find more information about a notification called documents as follows:

sem get notifications documents

You can edit that notification as follows:

sem edit notifications documents

The aforementioned command will take you to your configured text editor. If your changes are syntactically correct, you will get an output similar to the next:

$ sem edit notifications documents
Notification 'documents' updated.

If there is a syntactical error in the new file, the sem reply will tell you more information about the error but any changes you made to the notification will be lost.

Last, you can delete an existing notification named documents as follows:

sem delete notification documents

The output of the sem delete notification documents command is as follows:

$ sem delete notification documents
Notification 'documents' deleted.

Working with pipelines#

Listing pipelines#

The sem get pipelines command returns the list of pipeline for a Semaphore 2.0 project. If you are inside the directory of a Semaphore project, then you will not need to provide sem the name of the project as this will be discovered automatically.

However, if you want list of pipelines for some project other than the one you are currently in you can use the -p flag to declare the Semaphore project that interests you.

So, the sem get pipelines command can have the following two formats:

sem get pipelines
sem get pipelines -p [PROJECT NAME]

Listing pipelines example#

The following command will return the last 30 pipelines of the S1 project:

sem get pipelines -p S1

Describing a pipeline#

The sem get pipeline command followed by a valid Pipeline ID will return a description of the specified pipeline.

Describing a pipeline example#

You can find more information about the pipeline with the Pipeline ID of c2016294-d5ac-4af3-9a3d-1212e6652cd8 as follows:

sem get pipeline c2016294-d5ac-4af3-9a3d-1212e6652cd8

Rebuilding a pipeline#

You can rebuild an existing pipeline with the help of the sem rebuild pipeline command, that has the following format:

sem rebuild pipeline [Pipeline ID]

Note that sem rebuild pipeline will perform a partial rebuild of the pipeline as only the blocks that failed will be rerun.

Rebuilding a pipeline example#

Rebuilding the pipeline with a Pipeline ID of b83bce61-fdb8-4ace-b8bc-18be471aa96e will return the next output:

$ sem rebuild pipeline b83bce61-fdb8-4ace-b8bc-18be471aa96e
{"pipeline_id":"a1e45038-a689-460b-b3bb-ba1605104c08","message":""}

The --follow flag#

The general form of the sem get pipeline command when used with the --follow flag is as follows:

sem get pipeline [RUNNING Pipeline ID] --follow

The --follow flag makes the sem get pipeline [RUNNING Pipeline ID] command to be repeatedly called until the pipeline reaches terminal state.

The --follow flag is particularly useful in the following two cases:

If you want to look at how a build is advancing without using the Semaphore Web Interface (e.g. when you are prototyping something).
If you want to be notified when pipeline is done (e.g. in shell scripts).

The --follow flag example#

The --follow flag can be used on a running pipeline with a Pipeline ID of 9bfaf8d6-05c8-4397-b764-5f0f574c8e64 as follows:

sem get pipeline 9bfaf8d6-05c8-4397-b764-5f0f574c8e64 --follow

Working with workflows#

Listing workflows#

The sem get workflows command returns the list of workflows for a Semaphore 2.0 project. If you are inside the directory of a Semaphore project, then you will not need to provide sem the name of the project as this will be discovered automatically.

However, if you want the list of workflows for some project other than the one you are currently in, you can use the -p flag to directly specify the Semaphore project that interests you.

So the sem get workflows has the following two formats:

sem get workflows
sem get workflows -p [Project Name]

Listing workflows examples#

Finding the last 30 workflows for the S1 Semaphore project is as simple as executing the following commands:

sem get workflows -p S1

If the project name does not exist, you will get an error message.

If you are inside the root directory of the S1 Semaphore project, then you can also execute the next command to get the same output:

sem get workflows

Describing a workflow#

Each workflow has its own unique Workflow ID. Using that unique Workflow ID you can find more information about that particular workflow using the next command:

sem get workflow [WORKFLOW ID]

The output of the previous command is a list of pipelines that includes promoted and auto promoted pipelines.

Describing a workflow example#

Finding more information about the Workflow with ID 5bca6294-29d5-4fd3-891b-8ac3179ba196 is as easy as follows:

$ sem get workflow 5bca6294-29d5-4fd3-891b-8ac3179ba196
Label: master

PIPELINE ID                            PIPELINE NAME            CREATION TIME         STATE
9d5f9986-2694-43b9-bc85-6fee47440ba7   Pipeline 1 - p1.yml      2018-10-03 09:37:59   DONE
55e94adb-7aa8-4b1e-b60d-d9a1cb0a443a   Testing Auto Promoting   2018-10-03 09:31:35   DONE

Please note that you should have the required permissions in order to find information about a Workflow.

Rebuilding a workflow#

You can rebuild an existing workflow using the following command:

sem rebuild workflow [WORKFLOW ID]

Note that sem rebuild workflow will perform a full rebuild of the specified workflow. A new workflow will be created as if a new commit was pushed to GitHub.

Rebuilding a workflow example#

You can rebuild a workflow with a Workflow ID of 99737bcd-a295-4278-8804-fff651fb6a8c as follows:

$ sem rebuild wf 99737bcd-a295-4278-8804-fff651fb6a8c
{"wf_id":"8480a83c-2d90-4dd3-8e8d-5fb899a58bc0","ppl_id":"c2016294-d5ac-4af3-9a3d-1212e6652cd8"}

The output of sem rebuild wf command is a new Workflow ID and a new pipeline ID as the sem rebuild workflow command creates a new workflow based on an existing one.

Help commands#

The last group of sem commands includes the sem help and sem version commands, which are help commands.

sem help#

The sem help command returns information about an existing command when it is followed by a valid command name. If no command is given as a command line argument to sem help, a help screen is printed.

sem help example#

The output of the sem help command is static and identical to the output of the sem command when executed without any command line arguments.

Additionally, the help command can be also used as follows (the connect command is used as an example here):

sem connect help

In that case, help will generate information about the use of the sem connect command.

sem version#

The sem version command requires no additional command line parameters and returns the current version of the sem tool.

sem version example#

The sem version command displays the used version of the sem tool. As an example, if you are using sem version 0.4.1, the output of sem version will be as follows:

$ sem version
v0.8.17

Your output might be different.

Additionally, the sem version command cannot be used with the -f flag and does not create any additional output when used with the -v flag.

Flags#

The --help flag#

The --help flag, which can also be used as -h, is used for getting information about a sem command or sem itself.

The --verbose flag#

The --verbose flag, which can also be used as -v, displays verbose output – you will see the interaction and the data exchanged between sem and the Semaphore 2.0 API.

This flag is useful for debugging.

The -f flag#

The -f flag allows you to specify the path to the desired YAML file that will be used with the sem create or sem apply commands.

Additionally, -f can be used for creating new secrets with multiple files.

Last, the -f flag can be used as --file.

The --all flag#

The --all flag can only be used with the sem get jobs command in order to display the most recent jobs of the current organization, both running and finished.

Defining an editor#

The sem utility chooses which editor to use by following the next process:

Using the value of the editor property. This value can be set using the sem config set editor command
From the value of the EDITOR environment variable, if it is set
If none of the above exists, sem will try to use the vim editor

The `sem config set editor` command#

You can define that you want to use the nano editor for editing Semaphore resources by executing the following command:

sem config set editor nano

The EDITOR environment variable#

The EDITOR environment variable offers a way of defining the editor that will be used with the session of the sem edit command.

You can check whether the EDITOR environment variable is set on your UNIX machine by executing the following command:

echo $EDITOR

If the output is an empty line, then then EDITOR environment variable is not set. You can set it to the nano editor as follows:

$ export EDITOR=nano
$ echo $EDITOR
nano

The sem utility also supports custom flags in the EDITOR environment variable, like EDITOR="subl --wait".

Command aliases#

The words of each line that follows, which represent resource types, are equivalent:

project, projects and prj
dashboard, dashboards and dash
secret and secrets
job and jobs
notifications, notification, notifs and notif
pipelines, pipeline and ppl
workflows, workflow and wf

As an example, the following three commands are equivalent and will return the same output:

sem get project
sem get prj
sem get projects