Configuring clan

clan is configured using either YAML, command-line arguments or both.

By default clan will look for a YAML file called clan.yml. This can be configured using the -c command line flag. The basic structure of this file is:

Global configuration

The following is a list of properties that may be specified in as global configuration. Note that these may also be specified using command line arguments. Some properties can also be specified on a per-query basis. If there is a disagreement, the values will be preferred in the following order:

  • Command-line values
  • Query configuration in YAML
  • Global configuration in YAML


The ID of the Google Analytics property to query.


The start date of all queries, in YYYY-MM-DD format.


The end date of all queries, in YYYY-MM-DD format. Supersedes ndays if both are specified.


A number of days from the start date to report on. Superseded by end-date if both are specified.


If specified, results will be limited to URLs from this domain.


If specified, results will be limited to URLs with this prefix.

Query configuration

Individual queries support the following properties.


A description of the query. Will be used as a display name when rendering a text report.


A list of Google Analytics metrics to be reported.

For details about all metrics you can report on, see the Google Analytics Core Reporting API docs.


A list of Google Analytics metrics on which to segment the data. Not that these are pairwise not hierarchical. If your query configuration looked like:

- name: Pageviews by device and browser
      - "ga:pageviews"
      - "ga:deviceCategory"
      - "ga:browser"
      - "-ga:pageviews"

Then your resulting report would enumerate the most popular combinations of device and browser, not the most popular devices further subdivided by most popular browser.


A list of Google Analytics metrics to sort by. Prefix a value with a - to sort in descending order.


A Google Analytics query filter expression to apply to the data. This will be “ANDed” togther with any filters automatically generated from other configuration options such as domain or prefix.