Skip to main content

CLI Installation

Prerequisites

Before you begin, make sure your environment meets the following requirements:

info

If you are using OpenShift, you need to use the group id from the uid-range assigned to the project. Review the section on OpenShift Deployment for more details.

If you are using a custom StorageClass, you can specify the StorageClass to use for persistent volumes. Review the section on Using a custom StorageClass instead of the default one for more details.

1. Install the Causely CLI

Run the following command to download and install the Causely CLI:

bash -c "$(curl -fksSL https://install.causely.ai/install.sh)"
info

The Causely CLI simply wraps Helm. If you prefer, you can alternatively run Helm commands directly. See Helm Installation

2. Install the Causely Agent

Step 1: Retrieve Your Access Token

  1. Visit https://portal.causely.app and log in.
  2. Click on the gear icon in the top-right corner and select Integrations
  3. Click the Details 🗝️ button and copy your access token to use in the next step.

Step 2: Install via CLI

Run the following command by replacing <my_token> with your access token.

causely agent install --token <my_token>
note

If you have not installed the CLI in your PATH, make sure to run the command from absolute path, for example ~/bin/causely.

This installs Causely agents into the cluster defined by your current kubectx context. To specify a custom cluster name, see CLI Options below.

Step 3: Review Discovery

You have successfully installed Causely! Navigate to https://portal.causely.app to verify your environment has been discovered. You should see entities populated in the Topology view. As root causes are identified, they will appear in the Diagnose and Prevent menus.

CLI Options

You can see a complete list of options for customizing the installation by using the --help option.

causely agent --help

Here's a list of possible options:

causely agent install --namespace <namespace> --repository <repo> --tag <version> --cluster-name <my_cluster_name> --kube-context <my_kubectx> --values <causely-values.yaml>

Use a Custom Values File

To specify additional configurations - like a specific image tag, integrations, webhook notifications, etc - you can do this by creating a causely-values.yaml file. Below is an example of common values used for installation.

global:
cluster_name: <my_cluster_name>
image:
tag: <version> # Locate latest version in Causely Portal > Integrations > Agents
mediator:
gateway:
token: <my_token> # Locate your token in Causely Portal > Integrations > Details

Now specify the --values parameter for installation:

causely agent install --values ./causely-values.yaml

Custom Labels

You can scope the Causely interface to specific components out-of-the-box (clusters, namespaces, services). Causely can also use labels to provide users with additional scopes - this can be accomplished by adding the following to your causely-values.yaml.

label_semconv:
scopes:
geography:
- 'app.kubernetes.io/geography'
environment:
- 'app.kubernetes.io/environment'
customer:
- 'app.kubernetes.io/customer'
team:
- 'app.kubernetes.io/team'
product:
- 'app.kubernetes.io/product'
project:
- 'app.kubernetes.io/project'
service:
- 'app.kubernetes.io/service'

Telemetry Sources

You can add additional data sources to Causely which expands Causely's causality map to help identify root causes. Some data sources require you to update your causely-values.yaml file. For more details on Telemetry Sources, see Telemetry Sources.

Workflow Integrations

Causely can automatically send identified root causes to your existing notification and observability tools. To explore integrations with Slack, Grafana, Opsgenie, and more, visit our Workflow Integrations page. You'll find setup instructions for webhooks (via causely-values.yaml) and details on our Grafana plugin, with additional native integrations coming soon.

Helm Installation

The Causely CLI simply wraps Helm. If you prefer, you can run Helm commands directly to manage your Causely installation.

Per-Service Threshold Configuration (via CLI)

Causely now supports custom latency and error rate thresholds on a per-service basis, giving teams more control over how symptoms are detected and when SLO violations are flagged.

By default, Causely uses machine-learned thresholds to detect anomalies in latency and error rate. While effective in many environments, these learned thresholds may not always reflect service-specific expectations or the team's own definitions of what constitutes an issue.

To address this, you can now override learned thresholds via Kubernetes service labels, enabling fine-grained control without modifying code or dashboards.

Use Cases

  • Define stricter or looser thresholds for sensitive or noisy services.
  • Align Causely's detection logic with your own SLO definitions.
  • Improve trust and reduce false positives by tuning detection thresholds explicitly.

How to Configure Thresholds

Apply the appropriate labels to your Kubernetes service resources using kubectl. You can configure both latency and error rate thresholds:

kubectl label svc -n <namespace> <service-name> causely.ai/latency-threshold=<value-in-ms>
kubectl label svc -n <namespace> <service-name> causely.ai/error-rate-threshold=<value-between-0-and-1>

Example

kubectl label svc -n causely victoriametrics causely.ai/latency-threshold=500.0
kubectl label svc -n causely victoriametrics causely.ai/error-rate-threshold=0.01

Notes

Visit the Customize your Installation page to learn more about customizing your installation.

We recommend that you connect additional telemetry sources to help Causely identify root causes in your environment. Visit the Telemetry Sources page to learn more about the data sources that Causely supports.

To push insights into your workflows, visit the Workflow Integrations page.