Get started
Calyptia CLI

Calyptia CLI

Calyptia CLI is a command-line tool that offers many of the same features as the Calyptia Core dashboard. For example, you can use Calyptia CLI to deploy and update pipelines, create fleets, and install Core Operator in your Kubernetes cluster.

Install Calyptia CLI

Calyptia CLI is compatible with Linux, macOS, and Windows for both arm64 and x86_64 architectures. Use one of the following methods to install Calyptia CLI:

If you deployed Calyptia Core on a Linux server, Calyptia CLI was already installed locally on your behalf. You don't need to install it again.

Homebrew

To install Calyptia CLI using Homebrew, run the following commands:

brew tap calyptia/tap
brew install calyptia

Curl

To install Calyptia CLI using curl, run the following command, which is the same for both Zsh and Bash:

curl -sSfl https://raw.githubusercontent.com/calyptia/cli/main/install.sh | bash

Direct download

To install Calyptia CLI by downloading its files directly:

  1. Go to the Calyptia CLI release page (opens in a new tab).
  2. Locate the latest release artifact and download the .tar.gz archive that corresponds to your operating system and architecture.
  3. Extract the Calyptia CLI binary from the archive that you downloaded.
  4. Run the executable file to install Calyptia CLI.

Alternatively, you can download the Calyptia CLI source code from its release page and compile it yourself.

Setup

After you've installed Calyptia CLI, refer to these sections to complete your setup and learn more about supported commands.

Authenticate with Calyptia services

To authenticate your Calyptia CLI instance:

  1. Go to the Calyptia Core dashboard (opens in a new tab).

  2. In the navigation menu, select Settings > Generate API key.

  3. Under Generate API key, enter a name for your new API key, then select Generate.

  4. Run the following command in Calyptia CLI:

    calyptia config set_token KEY

    Replace KEY with the value of the API key you generated in the previous step.

Enable autocomplete

Calyptia CLI includes an optional autocomplete feature that suggests command names as you type. To enable this feature:

  1. Run the following command to view a list of supported shell environments:

    calyptia completion -h
  2. Run the following command:

    calyptia completion ENV -h

    Replace ENV with the name of your shell environment (for example, bash).

  3. Follow any additional instructions that print in your terminal. Depending on your environment, you might need to install additional dependencies.

View command list

To view a full list of available commands and flags, run:

calyptia help

You can also prepend calyptia help to a specific command to view more information about that command.

Core Instance operations

You can use Calyptia CLI to perform the following Core Instance operations.

Install Core Instance and Core Operator

If you deployed Calyptia Core inside a Kubernetes cluster, Calyptia CLI must be able to access that cluster. If you deployed Calyptia Core on a Linux server, you must run Calyptia CLI from inside that server environment.

You can use a single command to install Core Instance and Core Operator at the same time. The Core Operator installation includes custom resource definitions (CRDs) and the operator image.

To install Core Instance and Core Operator:

  1. Update Calyptia CLI. Because Core Instance versions are dependent on your Calyptia CLI version, the latest version of Calyptia CLI installs the latest version of Core Instance.

  2. Run the following command:

    calyptia config set_token KEY &&
      calyptia install operator &&
      calyptia create core_instance operator --name INSTANCE --wait

    Replace KEY with the value of the API key you generated to authenticate with Calyptia services and INSTANCE with the name of your Calyptia Core instance.

Upgrade Core Instance

If you deployed Calyptia Core inside a Kubernetes cluster, Calyptia CLI must have access that cluster. If you deployed Calyptia Core on a Linux server, you must run Calyptia CLI from inside that server environment.

To upgrade Core Instance by using Calyptia CLI:

  1. Run the following command to update Core Operator:

    calyptia update operator --version VERSION

    Replace VERSION with the latest version of the Core Instance binary.

  2. Run the following command to update Core Instance:

    calyptia update core_instance operator --version VERSION

    Replace VERSION with the same value from the previous step.

Both steps use the same VERSION value because Core Instance and Core Operator are packaged in the same binary.

Configure Kubernetes deployment

If you deployed Calyptia Core in a Kubernetes cluster, you can use Calyptia CLI to configure additional parameters and make sure that your Core Instance adheres to any other Kubernetes policies that you've set.

Namespaces

When you install Core Operator, use the --kube-namespace flag to set the namespace for your Core Operator installation. However, be aware that Core Operator CRDs do not support namespace scoping.

Tolerations and taints

Requires Core Instance version 2.8.4 or later and Calyptia CLI version 1.7.2 or later.

Tolerations and taints (opens in a new tab) can help you take advantage of high-availability hardware by ensuring that your deployments spread evenly.

To specify tolerations, use the --tolerations flag and key1=Equal:value1:Execute syntax.

Annotations

To set custom annotations, use the --annotations flag and annotation1=value1,annotation2=value2 syntax.

Pipeline operations

You can use Calyptia CLI to perform the following pipeline operations.

Create a pipeline

To create a pipeline:

  1. Create a YAML configuration file. For example, this configuration file specifies a pipeline that uses mock data as a source and standard output as a destination:

    pipeline:
       inputs:
          - dummy: '{"message":"dummy"}'
             rate: "1"
             samples: "0"
             start_time_sec: "-1"
             start_time_nsec: "-1"
             Name: dummy
             tag: dummy.92a99f85-50b8-401d-a619-a52b14288f21
       filters:
          - Name: lua
             match: dummy.92a99f85-50b8-401d-a619-a52b14288f21
             active: "false"
       outputs:
          - format: json
             Name: stdout
             Match_Regex: ^(?!.*_calyptia_cloud).*$
  2. Run the following command:

    calyptia create pipeline --config-file CONFIG --core-instance INSTANCE --name PIPELINE --skip-config-validation

    Replace CONFIG with the name of your configuration file, INSTANCE with the name of your Core Instance, and PIPELINE with the name you'd like to give your new pipeline.

Get pipeline IDs

Calyptia assigns each pipeline a unique ID.

To retrieve a list of pipeline IDs, run the following command:

calyptia get pipelines --core-instance INSTANCE --show-ids

Replace INSTANCE with the name of your Core Instance.

View configuration history

Calyptia saves a history of each pipeline's configuration. To view this history, you can run either of the following commands:

calyptia get pipeline_config_history --pipeline PIPELINE
calyptia get pipeline PIPELINE --include-config-history

Replace PIPELINE with either the name or unique ID of the pipeline whose history you'd like to view.

Limit results

Use the --last flag to display only a subset of snapshots. For example, to return a list of the last five snapshots, run:

calyptia get pipeline_config_history --pipeline my-pipeline --last 5

View individual changes

Use the -o yaml flag to view the individual changes behind each snapshot:

calyptia get pipeline_config_history --pipeline my-pipeline -o yaml

Revert pipeline configuration

⚠️

If you used the --skip-config-validation flag when you created or modified a pipeline, you must also include that flag when you run the rollout command for that pipeline.

To revert a pipeline to a previous configuration, use the rollout command:

calyptia rollout pipeline PIPELINE --to-config-id HISTORY

Replace PIPELINE with either the name or unique ID of the pipeline whose configuration you'd like to revert and HISTORY with the relevant snapshot ID.

You can also use the --steps-back flag to revert a pipeline by specifying how many steps to move back. For example, to revert a pipeline named my-pipeline to its immediate previous configuration, run:

calyptia rollout pipeline my-pipeline --steps-back 1

Upgrade pipeline version

To upgrade a pipeline's underlying binary file, use the update pipeline command and the --image flag:

calyptia update pipeline PIPELINE --image ghcr.io/calyptia/core/calyptia-fluent-bit:VERSION

Replace PIPELINE with either the name or unique ID of the pipeline you'd like to modify and VERSION with the latest version of the Calyptia pipeline.

Modify pipeline network settings

After you deploy or update a pipeline that has a network-based source, Calyptia automatically load-balances that pipeline using Kubernetes services (even if you deployed Calyptia Core on a Linux server).

By default, Calyptia uses the LoadBalancer network service. You can modify this behavior by running the following command:

calyptia update pipeline PIPELINE --service-type SERVICE

Replace PIPELINE with either the name or unique ID of the pipeline whose network setting you'd like to modify and SERVICE with the service type you'd like to use. Possible service type values are LoadBalancer, NodePort, and ClusterIP.

Scale a pipeline

To scale a pipeline, use the --replicas flag:

calyptia update pipeline PIPELINE --replicas REPLICAS

Replace PIPELINE with either the name or unique ID of the pipeline you'd like to scale and REPLICAS with the number of replicas you'd like to create.

Add pipeline files

By default, each pipeline includes a file that lists the parsers used by that pipeline. You can also add your own files to a pipeline, including certificates, stream processor jobs, and custom Lua scripts.

To add files to a pipeline, use the --file flag:

calyptia update pipeline PIPELINE --file FILENAME

Replace PIPELINE with either the name or unique ID of your pipeline and FILENAME with the name of the file to add. Files must be less than 10 MB and must not include a file extension.

After you've added a file, you can access it through the {{ files.FILENAME }} variable in configuration files and the Calyptia Core Dashboard.

Add encrypted file

To encrypt pipeline files, use the --encrypt-files flag. Calyptia uses RSA‑OAEP encryption with a 2048-bit key.

Add pipeline secrets

To add secrets to a pipeline, run the following command:

calyptia update pipeline --secrets-file FILE --secrets-format FORMAT

Replace FILE with the name of your secrets file and FORMAT with the format of that file. Possible format values are auto, env, json, and yaml.

Delete a pipeline

To delete a pipeline, run the following command:

calyptia delete pipeline PIPELINE

Replace PIPELINE with either the name or unique ID of the pipeline you'd like to delete.

Source code

The source code for Calyptia CLI is publicly available on GitHub (opens in a new tab). You can use this to build your own wrapper around Calyptia CLI or incorporate its code into your CI/CD workflow.