> ## Documentation Index
> Fetch the complete documentation index at: https://docs.validio.io/llms.txt
> Use this file to discover all available pages before exploring further.

# About 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 with some added functionality, and is also used to configure Validio through Infrastructure-as-Code (IaC).

## Install the Validio CLI

The Validio CLI is published as a Python package on PyPI as `validio-cli`. You can use a Python package installer, such as `pip`, to install the CLI in your desired environment:

```bash title="Bash" theme={null}
pip install validio-cli
```

To configure the credentials that the CLI uses, see [Configure default API credentials](https://docs.validio.io/developer/getting-started.md#configure-default-api-credentials).

## Use the Validio CLI

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

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

```bash title="Bash" theme={null}
validio credentials get
NAME                     TYPE      AGE
my_gcp_credentials       GCP       7d
my_demo_credentials      DEMO      7d
```

### Commands

Each resource type has its own command, with subcommands such as `get` alongside type-specific actions:

| Command | Description |
| :- | :- |
| `channels` | Channels used for notifications |
| `code` | Plan or apply your configuration. See [Validio Code (IaC)](https://docs.validio.io/developer/validio-code.md). |
| `config` | Configuration for the Validio CLI and SDK |
| `credentials` | Credentials used for sources |
| `dbt` | dbt related commands |
| `filters` | Filters on sources |
| `incidents` | Incidents from validators |
| `integrations` | Integrations |
| `metrics` | Metrics and incidents from validators |
| `namespaces` | Namespaces used to separate resources |
| `notification-rules` | Notification rules for incidents |
| `plugins` | Run a plugin. Any executable on your `PATH` named `validio-<name>` runs as `validio plugins <name>`. |
| `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 |
| `validator-debug-queries` | Debug queries saved on validators |
| `validators` | Validators monitor the data from your sources |
| `version` | Show current version |
| `windows` | Windows used to group data for calculations |

### Help

Use the `--help` flag on any command or subcommand to show its available options. Run `validio --help` for the list of commands in your installed version.

In this example, `--help` shows the options for listing validators:

```bash title="Bash" theme={null}
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.                                             │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

## 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`: An identifier that you give an entity you create in the Validio platform, such as a source, validator, or window. A resource name is unique within its namespace for each type of resource, so a source and a validator in the same namespace can share a resource name.
* `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 use either:

* The `ID`.
* The `resource name` and `resource namespace`.

> [!NOTE]
>
> **Resource Name Format**
>
> 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 prints tabular output with a short summary. It can also print JSON output with full context with the `-o` or `--output` flag.

In this example, `--output json` prints JSON output with full context:

```bash title="Bash" theme={null}
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 organize and isolate resources into managed groups. Most CLI commands operate within a single namespace, so you need to specify which namespace to target:

1. **Per command:** Pass the `-n` or `--namespace` flag.
2. **Default:** Configure a default namespace with `validio config ns <namespace>`.

This example illustrates the namespace functionality:

```bash title="Bash" theme={null}
# List sources in a specific namespace
validio sources get -n example
NAME         TYPE  STATE  AGE
demo_source  DEMO  IDLE   1h

# Set a default namespace
validio config ns example
Default namespace set to 'example'

# Subsequent commands use the default namespace
validio sources get
NAME         TYPE  STATE  AGE
demo_source  DEMO  IDLE   1h
```

For creating namespaces and managing their members from the CLI, see [Namespaces](https://docs.validio.io/developer/getting-started/namespaces.md).

## Manage sources

You can use `sources` subcommands to start, stop, backfill, or reset your sources.

To start a source:

```bash title="Bash" theme={null}
validio sources start my_postgres_source
STARTING
```

You can also start all sources in a namespace:

```bash title="Bash" theme={null}
validio sources start --namespace=foo --all --auto-approve
```

To stop a source:

```bash title="Bash" theme={null}
validio sources stop my_postgres_source
STOPPING
```

To backfill a source:

```bash title="Bash" theme={null}
validio sources backfill my_postgres_source
BACKFILLING
```

To reset a source:

```bash title="Bash" theme={null}
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 a resource is moved, all of its children are moved with it.

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

```bash title="Bash" theme={null}
validio resources move --namespace namespace-a --target-namespace namespace-b
```

To move only specific resources, pass their resource names with the flag for their resource type:

```bash title="Bash" theme={null}
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, which removes the need for a separate move beforehand. See [Import resources](https://docs.validio.io/developer/validio-code/scenarios.md#import-resources).