Skip to main content

CLI Installation

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 Custom Installation 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.

Custom Installation Options​

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

  • Latency thresholds are specified in milliseconds.
  • Error rate thresholds are decimals between 0.0 and 1.0 (representing 0% to 100%).
  • Thresholds override the default learned values.
  • You can remove a label to revert back to learned behavior.

Suggest Additional Thresholds

We’re currently exploring ways to make threshold configuration more flexible via the Causely UI and support for additional metrics such as CPU and memory. If there are other thresholds you'd like to configure, please let us know.