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:

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

Identifiers

The following identifiers are used to differentiate entities in the Validio platform:

ID: A globally unique identifier for any entity in the Validio platform.
Resource name: 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 either:

The ID.
The resource name and resource namespace .

📘
Note
The resource name must have the following format:

Needs to contain only alphanumeric characters (uppercase or lowercase, a-z, A-Z) or -, _ or .

Must be between 2-253 characters in length

Output

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

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

Pass the flag -n or --namespace
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  
NAME  TYPE  STATE  AGE

# By manually specifying the namespace it will list the resource
validio sources get -n example  
NAME         TYPE  STATE  AGE  
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  
NAME         TYPE  STATE  AGE  
demo_source  DEMO  IDLE   1h

Help

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:           https://validio.company.com
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  
STARTING

validio sources stop my_postgres_source  
STOPPING

validio sources poll my_postgres_source  
POLLING

validio sources backfill my_postgres_source  
BACKFILLING

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. Only top level resources such as credentials or channels can be moved. When such resource is moved, all of its children will be moved with it.

In this example we move all resources from namespace-a to namespace-b:

validio resources move --namespace namespace-a --target-namespace namespace-b

It is also possible to move only specified resources by specifying the resource name as the desired flag, e.g:

validio resources move \
  --namespace namespace-a \
  --target-namespace namespace-b \
  --credential my-credential-a \
  --credential my-credential-b \
  --channel my-channel

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.

Install the Validio CLI

Use the Validio CLI

Identifiers

📘Note

Output

Namespaces

📘

Help

Store credentials

List resources

💡

Example 1

Example 2

Example 3

Manage sources

Move resources

Move resources when importing

📘
Note