CodSpeed CLI

CLI to gather performance data and upload performance reports to CodSpeed

The codspeed CLI is designed to be used both in local in CI environments.

The following CI providers are supported:

• GitHub Actions: Usage with @CodSpeedHQ/action is recommended.
• GitLab CI
• Buildkite

Other providers

If you want to use the CLI with another provider, you can open an issue or chat with us on Discord 🚀

You can check out the implementation of the supported providers for reference.

Installation

CODSPEED_RUNNER_VERSION=<insert-version> # refer to https://github.com/CodSpeedHQ/runner/releases for available versions
curl -fsSL https://github.com/CodSpeedHQ/runner/releases/download/$CODSPEED_RUNNER_VERSION/codspeed-runner-installer.sh | bash
source "$HOME/.cargo/env"

Refer to the releases page to see all available versions.

Usage

Note

For now, the CLI only supports Ubuntu 20.04, 22.04, 24.04 and Debian 11, 12.

First, authenticate with your CodSpeed account:

codspeed auth login

Then, run benchmarks with the following command:

codspeed run <my-benchmark-command>

# Example, using https://github.com/CodSpeedHQ/codspeed-rust
codspeed run cargo codspeed run

# Example, using https://github.com/CodSpeedHQ/pytest-codspeed
codspeed run pytest ./tests --codspeed

# Example, using https://github.com/CodSpeedHQ/codspeed-node/tree/main/packages/vitest-plugin
codspeed run pnpm vitest bench

Advanced usage

Installing tools before running

You can install executors and instruments before running the benchmark with the setup command:

codspeed setup

This is especially useful when configuring environments with tools such as docker.

Logging level

Use the CODSPEED_LOG environment variable to set the logging level:

CODSPEED_LOG=debug codspeed run ...

Changing the mode of the runner

By default, the runner will run the benchmark in the instrumentation mode. You can specify the mode with the --mode flag of the run command:

# Run in the `instrumentation` mode
codspeed run --mode instrumentation <my-benchmark-command>

# Run in the `walltime` mode
codspeed run --mode walltime <my-benchmark-command>

Warning

We strongly recommend not changing this mode unless you know what you are doing. Using the walltime mode on traditional VMs/Hosted Runners will lead to inconsistent data. For the best results, we recommend using CodSpeed Hosted Macro Runners, which are fine-tuned for performance measurement consistency. Check out the Walltime Instrument Documentation for more details.