ktx/docs-site/content/docs/cli-reference/ktx-connection.mdx

---
title: "ktx connection"
description: "List and test configured data sources."
---

Inspect configured connections in your KTX project. Connections define how KTX
reaches your data warehouse, BI tools, and context sources. Use `ktx setup` to
add, remove, or reconfigure connections.

## Command signature

```bash
ktx connection <subcommand> [options]
```

## Subcommands

| Subcommand | Description |
|-----------|-------------|
| `list` | List configured connections |
| `test <connectionId>` | Test a configured connection |

## Options

The `connection` command has command-level options for listing and testing
existing connections.

### `connection list`

| Flag | Description | Default |
|------|-------------|---------|
| `--json` | Print JSON output | `false` |

### `connection test`

| Flag | Description | Default |
|------|-------------|---------|
| `--json` | Print JSON output | `false` |

## Examples

```bash
# List all configured connections
ktx connection list

# Test a connection
ktx connection test my-warehouse
```

## Setup-managed connections

Run `ktx setup` when you need to add or reconfigure a connection. Interactive
setup includes the rich Notion page picker for selected root pages and the
Metabase mapping prompts for BI-to-warehouse mappings.

## Output

Commands with `--json` return machine-readable JSON suitable for scripts and
agents.

```json
{
  "connections": [
    {
      "id": "my-warehouse",
      "driver": "postgres"
    }
  ]
}
```

## Common errors

| Error | Cause | Recovery |
|-------|-------|----------|
| Connection test fails | Credentials, network access, database, warehouse, or schema is invalid | Verify the same URL with the database's native client, then rerun `ktx setup` and reconfigure the connection |
| Mapping validation fails during setup | BI database mappings do not point at valid warehouse connections | Rerun `ktx setup` and update the source mapping selections |
| Notion page picker cannot run | The terminal is non-interactive or Notion discovery failed | Rerun interactive `ktx setup`, or use non-interactive setup flags with explicit root page ids |