Skip to main content
The Evidence CLI lets you run and develop Evidence projects locally from the command line. It includes a development server for previewing your reports locally as you work, commands for running queries, viewing metadata, and validating your code. If you are going to use the CLI for development, you should set up the GitHub Integration.

​
Install

Installs to /usr/local/bin (falls back to ~/.local/bin if not writable).
Both evidence and evd commands are available after install.

​
Supported Platforms

  • macOS arm64 (Apple Silicon)
  • macOS x64 (Intel)
  • Linux x64
  • Linux arm64
  • Windows x64

​
Verify Installation

​
Getting Started

  1. Create a project in Evidence Studio and connect it to a GitHub repo.
  2. Clone the repo to your local machine.
  3. Log in to your Evidence account via the CLI:
  4. Start developing from inside your cloned project directory:
  5. Open a pull request on the repo. Evidence Studio will reply with a preview link. Merging the PR releases your changes.

​
Upgrade

The CLI checks for updates on startup. If a newer version is available, you’ll see a warning. If your version is below the minimum supported version, the CLI will require an upgrade before running.

​
Telemetry

The CLI reports anonymous usage so we can tell how many people use Evidence, which commands matter, and which versions are still in the wild. Nothing about your data, queries, file paths, or repository is ever sent.

​
Opting out

Any one of these turns telemetry off:
evidence telemetry status shows the current state and why. Telemetry is also skipped automatically on CI (CI, GITHUB_ACTIONS, GITLAB_CI, CIRCLECI, BUILDKITE, TF_BUILD, JENKINS_URL).

​
What is sent

One cli_command event per invocation, one cli_installed event from the install script, and — for evidence serve only — a serve_heartbeat once every 24 hours so long-running deployments stay counted, plus a serve_preflight_failed event (with a reason such as no_connection_yaml) when serve refuses to start, so we can spot broken self-host deployments. Requests carry your IP like any HTTP request; it is used for country-level geolocation only.

​
Project id

evidence init writes a random telemetry.id into evidence.config.yaml. It identifies the project, not you or your machine, and is what lets us count a self-hosted deployment once rather than once per container restart. Delete the key to opt a project out of that count.

​
When you are logged in

Commands that talk to Evidence Studio (launch, link, publish, models, and others) are authenticated API calls, and Studio records that your account and organization used the CLI, the same way it records use of the web app. Anonymous local usage is never linked to an account.