Configuring with YAML

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
property-id: "53470309"

# A list of queries to execute

    # Individual query configuration
    - name: Totals
          - "ga:pageviews"
          - "ga:uniquePageviews"
          - "ga:users"
          - "ga:sessions"

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:

  1. Command-line values
  2. Query configuration in YAML
  3. 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.

Per-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.