Get your first result with the CLI

Connect one supported non-production system, save one harmless standalone read, and run it. Exact connection fields, statement shapes, and results depend on the connector.

Before starting, create an account, install and authenticate the CLI, and choose your system in the connector directory. Use the connector guide's safe read example and least-privilege provider credentials.

Hosted execution cannot reach your laptop's localhost, loopback, or private network addresses by default. Do not disable TLS or expose a system publicly as a shortcut.

1. Connect your system

Prepare connection.json from the connector guide and the CreateDataSourceRequest schema. The schema defines the complete request envelope for every connector.

For example, download the complete PostgreSQL connection request, replace every angle-bracket placeholder, and keep read_only: true. The database role needs CONNECT on the database, USAGE on the required schemas, and SELECT on the required tables or views. This PostgreSQL request is an example; use the request fields and least-privilege permissions from the guide for the connector you choose.

Keep connection.json and referenced credential files outside Git with permissions restricted to your user. Use only synthetic data and non-production resources.

braidplane data-source test --file connection.json
braidplane data-source create --file connection.json

A successful draft test has no output. Creation returns safe metadata, never credentials. The saved data source should be active with a successful last test. This first saved success starts the free-trial clock.

To check the saved connection again later, run:

braidplane data-source test-stored '<data-source-slug>'

test-stored makes a live connection attempt using that data source's saved configuration and stored credentials. It records the success or failure on the data source and prints nothing when successful. It does not run a saved query or write pipeline data. A successful test starts the free trial if it has not started already.

2. Save one read

Save the connector guide's standalone read statement as operation.statement.json:

For a query without parameters:

braidplane query create --data-source '<data-source-slug>' \
  --name 'First read' --slug first-read \
  --statement-file operation.statement.json

If the statement contains a placeholder such as {{customer_id}}, define it in parameters.json:

[
  {
    "name": "customer_id",
    "data_type": "integer",
    "is_required": true
  }
]

Pass the definitions when creating the query:

braidplane query create --data-source '<data-source-slug>' \
  --name 'First read' --slug first-read \
  --statement-file operation.statement.json \
  --parameters-file parameters.json

The placeholder name and parameter name are case-sensitive and must match. See parameters and placeholders for pipeline literals, per-run input, environment values, secrets, and earlier step results.

3. Run and verify

For the parameterized example above:

braidplane query execute first-read --data-source '<data-source-slug>' \
  --parameters-json '{"customer_id": 42}'

For a query without parameters:

braidplane query execute first-read --data-source '<data-source-slug>'

Expect success. Compare the returned rows, documents, records, or file content with the connector guide's expected result and your synthetic source data. A connection test proves access; execution proves the saved read and its permissions work.

If execution fails, confirm the data-source slug, statement shape, parameters, and provider permissions, then test the saved connection and retry.

Clean up

braidplane query delete first-read --data-source '<data-source-slug>'
braidplane data-source delete '<data-source-slug>'

Delete local request and credential files when no longer needed. Deleting tutorial resources does not reset or extend the trial.

Next, read the pipeline specification reference or follow the PostgreSQL-to-S3 example.