Validio CLI

Command-Line Interface (CLI) to interact with the Validio platform through the SDK and API. The Validio CLI is a wrapper around the Validio SDK which includes some added functionality. The CLI is also used to configure Validio through Infrastructure-as-Code (IaC).

Install the Validio CLI

The Validio CLI is published as Python packages on PyPI as validio-cli.

You can use a Python package installer, such as ‘pip’, to install the CLI in your desired environment:

Install the CLI

pip install validio-cli

Use the Validio CLI

You can use the Validio CLI to interact with the Validio platform directly from the command-line interface.

In this example, the CLI prints a short summary of Credentials:

validio credentials get
NAME                     TYPE      AGE
my_gcp_credentials       GCP       7d
my_demo_credentials      DEMO      7d


Several identifiers are used to differentiate entities in the Validio platform:

  • ID: A globally unique identifier for any entity in the Validio platform.
  • Resource name: Currently, a globally unique identifier for any entity that you create in the Validio platform. For example Sources, Validators, and Windows.
  • Resource namespace: A defined logical grouping of created entities that have a resource name.

When you call commands that rely on unique identifiers you can choose to use either:

  • The ID.
  • The resource name and resource namespace .


By default, the CLI can print tabular output with a short summary. It can also print JSON output with full context with the -o or --output flag.

In this example, we use --output json to print JSON output with full context:

validio credentials get --output json
    "created_at": "2023-06-02T07:06:13.807000+00:00",
    "id": "CRD_3UG6s0L9TNadmYF-o_Ez4Q",
    "name": "My GCP Credentials",
    "resource_name": "my_gcp_credentials",
    "resource_namespace": "default",
    "typename__": "GcpCredential",
    "updated_at": "2023-06-02T07:06:13.807000+00:00"
    "created_at": "2023-06-02T11:08:41.108000+00:00",
    "id": "CRD_6BBgu06kQ8WzjGwuTMDR_Q",
    "name": "My Demo Credentials", 
    "resource_name": "my_demo_credentials",
    "resource_namespace": "default",
    "typename__": "DemoCredential",
    "updated_at": "2023-06-02T11:08:41.108000+00:00"


Namespaces are used to separate between similar resources. There are two ways you can specify what namespace to target:

  1. Pass the flag -n or --namespace
  2. Configure the default namespace by running validio config ns <your-default-namespace>


For more information about namespaces, refer to Validio API.

This example illustrates the namespace functionality:

# We will not get any result when we use the default namespace
validio sources get  

# By manually specifying the namespace it will list the resource
validio sources get -n example  
demo_source  DEMO  IDLE   1h

# We can configure the default namespace to use
validio config ns example  
Default namespace set to 'example'

# We will now target the 'example' namespace by default
validio sources get  
demo_source  DEMO  IDLE   1h


You can use the --help flag for any command or subcommand to show information on available options and functionality:

validio --help

 Usage: validio [OPTIONS] COMMAND [ARGS]...

 Validio CLI tool

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --install-completion          Install completion for the current shell.                          │
│ --show-completion             Show completion for the current shell, to copy it or customize the │
│                               installation.                                                      │
│ --help                        Show this message and exit.                                        │
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────╮
│ channels                      Channels used for notifications                                    │
│ code                          Plan or apply your configuration                                   │
│ config                        Configuration for the Validio CLI and SDK                          │
│ credentials                   Credentials used for Sources                                       │
│ dbt                           dbt related commands                                               │
│ incidents                     Incidents from validators                                          │
│ metrics                       Metrics and incidents from validators                              │
│ notification-rules            Notification rules for incidents                                   │
│ recommendations               Recommended validators for your Sources                            │
│ resources                     Manage resources                                                   │
│ segmentations                 Grouping of data for validation                                    │
│ segments                      Segments for a segmentation                                        │
│ sources                       Data sources to ingest data from                                   │
│ users                         Users in the Validio platform                                      │
│ validators                    Validators monitor the data from your sources                      │
│ version                       Show current version                                               │
│ windows                       Windows used to group data for calculations                        │

Store credentials

With API credentials, you can configure the CLI (and SDK) to always use the same endpoint, key, and secret.

Run validio config init and configure the endpoint URI, API access key, and API secret:

validio config init
Validio endpoint URI: 
API access key:                 APK_fxJmKsKjyVarmzdovac7gw
API access secret:              **************************

Use validio config get flag to show existing configuration and where the configuration file is located:

KEY                VALUE
Config path        /Users/<user>/Library/Application Support/validio/config.json
Default namespace  default
Endpoint           http://localhost:8889
Access key         APK_mVboIkAd4rXdxHYnQP2uog
Access secret      *****

List resources

You can list any resource by using subcommands for them.

Run validio --help to show available resources.


You can use the --help flag to see what options are available for each command.

Example 1

In this example, we list Credentials with the default tabular output format:

validio credentials get
NAME                         TYPE              AGE
default_postgres_credential  POSTGRE_SQL       3d

Example 2

In this example, we add -o json or --output json to show the output in JSON format:

validio credentials get --output json
    "created_at": "2023-05-23T08:59:07.096000+00:00",
    "id": "CRD_-z9jE2_dQzCV28CXGaafMw",
    "name": "My PostgreSQL credentials",
    "resource_name": "default_postgres_credential",
    "typename__": "PostgreSqlCredential",
    "updated_at": "2023-05-23T08:59:07.096000+00:00"

Example 3

In this example we use the –help flag when we list Validators:

validio validators get --help

 Usage: validio validators get [OPTIONS] [IDENTIFIER]

 Get validators

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────╮
│   identifier      [IDENTIFIER]  Name or ID of the resource to get of this type [default: None]               │
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --config-dir    -c      TEXT         Path to where config is stored [default: (dynamic)]                     │
│ --output        -o      [json|text]  Output format [default: text]                                           │
│ --namespace     -n      TEXT         Namespace to target [default: None]                                     │
│ --source                TEXT         List Validators for this Source (name or ID) [default: None]            │
│ --window                TEXT         List Validators for this Window (name or ID) [default: None]            │
│ --segmentation          TEXT         List Validators for this Segmentation (name or ID) [default: None]      │
│ --help                               Show this message and exit.                                             │

Manage sources

You can use sources subcommands to start, stop, poll, backfill, or reset your Sources:

validio sources start my_postgres_source  
validio sources stop my_postgres_source  
validio sources poll my_postgres_source  
validio sources backfill my_postgres_source  
validio sources reset my_postgres_source
Source has been successfully reset

Move resources

You can move resources from one namespace to another using validio resources move.

In this example we move all resources, specified in resources.json, from namespace-a to namespace-b:

validio resources move --namespace namespace-a --target-namespace namespace-b -f resources.json


Resources file

For more information about the resources file, refer to Specify resources to import.

Move resources when importing

You can also move resources when importing them, eliminating the need to perform a separate move beforehand. Refer to Import resources for more information about the resource file and resource types.