ktx connection

Inspect configured connections in your ktx project. Connections define how ktx reaches primary sources (databases and warehouses) and context sources (BI tools, modeling projects, and knowledge systems). Use ktx setup to add, remove, or reconfigure them.

Command signature

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

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

output

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. Context-source connectors report connector-specific details such as Metabase database count, Looker user, Notion bot, or Git repo URL.

output

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.

output

╭  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 context-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 context-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

On this page