CISTERN(1) | version 0.2.0dev0-6-g0c92981-dirty-linux-amd64

Nicolas Bedos


cistern – Continuous Integration Table Of Pipelines


cistern [-r REPOSITORY | --repository REPOSITORY] [COMMIT]

cistern -h | --help

cistern --version


cistern monitors the CI pipelines associated to a specific commit of a git repository.

cistern currently integrates with the following online services. Each of the service is one or both of the following:

Service Source CI URL
GitHub yes no
GitLab yes yes
AppVeyor no yes
CircleCI no yes
Travis CI no yes
Azure Devops no yes



Specify the commit to monitor. COMMIT is expected to be the SHA identifier of a commit, or the name of a tag or a branch. If this option is missing cistern will monitor the commit referenced by HEAD.


# Show pipelines for commit 64be3c6
cistern 64be3c6
# Show pipelines for the commit referenced by the tag '0.9.0'
cistern 0.9.0
# Show pipelines for the commit at the tip of a branch
cistern feature/doc



Specify the git repository to monitor. If REPOSITORY is the path of a local repository, cistern will monitor all the associated remotes. If REPOSITORY is a URL, cistern will monitor the corresponding online repository.

If this option is not set, cistern will behave as if it had been set to the path of the current directory.

Note that cistern will only monitor repositories hosted on GitLab or GitHub.


# Monitor pipelines of the git repository in the current directory
# Monitor pipelines of the repository specified by a web URL
cistern -r
cistern -r
# Git URLs are accepted
cistern -r
# A path referring to a local repository is valid too
cistern -r /home/user/repos/myrepo

-h, --help

Show usage of cistern


Print the version of cistern being run



Tag or branch associated to the pipeline


Identifier of the pipeline


Either “P” (Pipeline), “S” (Stage), “J” (Job) or “T” (Task)


State of the pipeline


Expected failure. Boolean indicating whether this step is allowed to fail without impacting the overall state of the pipeline


Date when the pipeline was created, started or finished


Time it took for the pipeline to finish


Name of the provider followed by the name of the pipeline, if any


URL of the step on the website of the provider


Below are the default commands for interacting with cistern.

Key Action
Up, k, Ctrl-p Move cursor up by one line
Down, j, Ctrl-n Move cursor down by one line
Right, l Scroll right
Left, h Scroll left
Ctrl-u Move cursor up by half a page
Page Up Move cursor up by one page
Ctrl-d Move cursor down by half a page
Page Down Move cursor down by one page
Home Move cursor to the first line
End Move cursor to the last line
< Move sort column left
> Move sort column right
! Reverse sort order
o, + Open the fold at the cursor
O Open the fold at the cursor and all sub-folds
c, - Close the fold at the cursor
C Close the fold at the cursor and all sub-folds
/ Open search prompt
Escape Close search prompt
Enter, n Move to the next match
N Move to the previous match
v View the log of the job at the cursor[a]
b Open associated web page in $BROWSER
q Quit
? Show help for interactive commands



cistern follows the XDG base directory specification [2] and expects to find the configuration file at one of the following locations depending on the value of the two environment variables XDG_CONFIG_HOME and XDG_CONFIG_DIRS:

  1. "$XDG_CONFIG_HOME/cistern/cistern.toml"
  2. "$DIR/cistern/cistern.toml" for every directory DIR in the comma-separated list "$XDG_CONFIG_DIRS"

If XDG_CONFIG_HOME (resp. XDG_CONFIG_DIRS) is not set, cistern uses the default value "$HOME/.config" (resp. "/etc/xdg") instead.


cistern uses a configuration file in TOML version v0.5.0 format.

The complete format of the configuration file is described in the example included in the release archives which is also available on GitHub

Minimal example

This is a minimal example of a configuration file focused mostly on setting up credentials. It should be enough to get you started running cistern.

# This is a configuration file for cistern that should be located at
# $XDG_CONFIG_HOME/cistern/cistern.toml

# List of columns displayed on screen. Available columns are 
# "ref", "pipeline", "type", "state", "created", "started",
# "finished", "duration", "xfail", "name", "url"
columns = ["ref", "pipeline", "type", "state", "started", "duration", "name", "url"]

# Name of the column used for sorting the table prefixed by an
# optional "+" (ascending order) or "-" (descending order).
sort = "-started"

# The sections below define credentials for accessing source 
# providers (GitHub, GitLab) and CI providers (GitLab, Travis,
# AppVeyor, Azure Devops, CircleCI).
# Feel free to remove any section as long as you leave one
# section for a source provider and one for a CI provider.
# When an API token is not set or set to the empty string,
# cistern will still run but with some limitations:
#     - GitHub: cistern will hit the rate-limit for
#     unauthenticated requests in a few minutes
#     - GitLab: cistern will NOT be able to access pipeline
#     jobs

### GITHUB ###
# GitHub API token (optional, string)
# GitHub token management:
token = ""

### GITLAB ###
# GitLab instance URL (optional, string, default:
# "")
# (the GitLab instance must support GitLab REST API V4)
url = ""

# GitLab API token (optional, string)
# token management:
token = ""

### TRAVIS CI ###
# URL of the Travis instance. "org" and "com" can be used as
# shorthands for the full URL of and
# (string, mandatory)
url = "org"

# API access token for the travis API (string, optional).
# Travis tokens are managed at:
#    -
#    -
token = ""

# Define another account for accessing
url = "com"
token = ""

### APPVEYOR ###
# AppVeyor API token (optional, string)
# AppVeyor token managemement:
token = ""

### CIRCLECI ###
# Circle CI API token (optional, string)
# See
token = ""

# Azure API token (optional, string)
# Azure token management is done at via
# the user settings menu
token = ""




cistern relies on the following local executables:


Monitor pipelines of the current git repository

# Move to a directory containing a git repository of your choosing
git clone && cd cistern
# Run cistern to list the pipelines associated to the last commit of the repository 

# Show pipelines associated to a specific commit, tag or branch
cistern a24840c
cistern 0.1.0
cistern master

Monitor pipelines of other repositories

# Show pipelines of a repository identified by a URL or path
cistern -r        # Web URL
cistern -r        # Git URL
cistern -r                # URL without scheme
cistern -r /home/user/repos/repo                    # Path to a repository

# Specify both repository and git reference
cistern -r master


Questions, bug reports and feature requests are welcome and should be submitted on GitHub.


  1. cistern repository
  2. XDG base directory specification