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 databases, warehouses, BI tools, source projects, and knowledge
systems. Use `ktx setup` to add, remove, or reconfigure them.

## Command signature

```bash
ktx connection                       # list all configured connections
ktx connection list                  # explicit list
ktx connection test [connectionId]   # test one (or all, when omitted)
```

Bare `ktx connection` lists configured connections. `ktx connection test`
with no positional and no flag tests every configured connection.

## Subcommands

| Subcommand | Description |
|-----------|-------------|
| (none) | List configured connections (alias for `list`) |
| `list` | List configured connections |
| `test [connectionId]` | Test one configured connection; omit the id (or pass `--all`) to test every connection |

## Options

`ktx connection` uses the shared global options such as `--project-dir` and
`--debug`.

### `connection test`

| Flag | Description | Default |
|------|-------------|---------|
| `--all` | Test every configured connection and print a summary list | implicit when no `connectionId` is supplied |

Project directory resolution defaults to `KTX_PROJECT_DIR`, then the nearest
`ktx.yaml`, then the current working directory.

## Examples

```bash
# List all configured connections
ktx connection

# Test every configured connection
ktx connection test

# Test one connection
ktx connection test my-warehouse

# Test every connection explicitly
ktx connection test --all

# Test a connection from outside the project
ktx connection test my-warehouse --project-dir ./analytics
```

## 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

`ktx connection` (or `ktx connection list`) prints a table of configured ids
and drivers.

```text
ID            DRIVER
my-warehouse  postgres
```

`ktx connection test <connectionId>` performs a lightweight connection probe.
Native database connections report `Status: ok` when the connector probe
passes. Source connectors report connector-specific details such as Metabase
database count, Looker user, Notion bot, or Git repo URL.

```text
Connection test passed: my-warehouse
Driver: postgres
Status: ok
```

`ktx connection test` (bare) and `ktx connection test --all` print one row per
configured connection and exit non-zero if any probe fails.

```text
╭  connection test --all
│
│  • warehouse  postgres  ✓ ok      Status: ok
│  • metabase   metabase  ✓ ok      Databases: 2
│
╰  2 tested · 2 passed
```

## Common errors

| Error | Cause | Recovery |
|-------|-------|----------|
| No connections configured | The project has no entries under `connections` | Run `ktx setup` and add a database or source connection |
| 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 |