Mako CLI

The Mako command-line interface (CLI) tool can be used to gain programmatic access to the same Mako data that’s available on the dashboard. This tool is used by benchmark owners to manage their benchmarks and runs.

Before you can use the Mako CLI, you’ll have to set up authentication.

To learn how to build the Mako command-line tool, please read BUILDING.MD.

Once the command-line binary is built, use its built-in help to get a list of subcommands:

mako help

As you might expect, each subcommand has its own help:

mako help display_benchmark

Common operation: Creating a Project

A Mako project is defined by the ProjectInfo object in mako.proto.

First, write a config file for the project. The project name serves as the unique identifier and is evaluated as lowercase (i.e. case-insensitive). To create the project, execute the following:

PROJECT_PATH=~/myproject/my_project.config
mako create_project ${PROJECT_PATH}

If the create_project subcommand completes successfully, you can start creating benchmarks under it.

To update the project, make changes to the config file and execute the following:

mako update_project ${PROJECT_PATH}

Common operation: Fetching a Project

The get_project subcommand fetches the project configuration given the project name.

PROJECT_NAME=my_project
mako get_project --project_name=${PROJECT_NAME}

Common operation: Creating a Benchmark

We’re going to use the create_benchmark subcommand. To see the help for this subcommand:

mako help create_benchmark

Let’s leave the path blank so that we can create the benchmark from a template. Execute:

mako create_benchmark

This will bring the template up in your shell’s default editor. Replace the template text with your own information. To read about benchmarks and their role in Mako, read CONCEPTS.md.

Now save and quit your editor. Assuming there are no syntax errors or other issues with your data, the create_benchmark subcommand should complete successfully and report the https://mako.dev URL where you can find your benchmark.

If you prefer to store a version of your benchmark, the create_benchmark subcommand works with files too.

First use the display_benchmark subcommand to get the benchmark and write it to file:

BENCHMARK=5251279936815104
BENCHMARK_PATH=~/myproject/my_benchmark.config
mako display_benchmark --benchmark_key=${BENCHMARK} > ${BENCHMARK_PATH}

Then you can save that config (e.g. in source control, along with your performance test code). When you make changes to the file, write them back to Mako:

mako update_benchmark ${BENCHMARK_PATH}

Common operation: Listing Your Benchmarks

The list_benchmarks subcommand makes it easy to list the benchmark keys for the benchmarks you own.

For example, to get all the benchmarks for your project, execute:

PROJECT=MakoExample
mako list_benchmarks --project_name=${PROJECT}

To get the benchmarks that you are an owner of, execute:

mako list_benchmarks --owner=youremail@example.com

Common operation: Listing Runs With Filters

The list_runs subcommand lists run keys that match a filter.

For example, to get all the run keys for a benchmark, execute:

BENCHMARK=5675196467904512
mako list_runs --benchmark_key=${BENCHMARK}

To get only runs matching a set of tags, use the --tag_list flag:

TAGS=num_samplers=1,env=exclusive
mako list_runs --benchmark_key=${BENCHMARK} -tag_list=${TAGS}

Learn more about tags at CONCEPTS.md.

Use the subcommand help to learn about the other attributes you can filter by.