Data sources

These commands run in the CLI only. Data sources and connections are not available over MCP.

Connect and manage a data source

CLI only

Creating a data source in the CLI auto-creates a pack with the source’s name. To attach the source to an existing pack instead, pass --pack-id. You need contribute access to that pack.

edisyl data-sources test-connection --type <connector> --config-file <f>
edisyl data-sources create --name "<name>" --type <connector> --config-file <f> --database <db>
edisyl data-sources introspect <id>     # re-run table discovery only
edisyl data-sources enrich <id>         # study every model: run after create, and after schema changes
edisyl data-sources study <id> <db.schema.table>...   # study only these tables
edisyl data-sources models <id>         # list indexed models (the names `study` takes)
edisyl data-sources list [--pack-id <id>]
edisyl data-sources get <id>            # where it's mounted, its scope, what happens to new tables
edisyl data-sources test <id>           # test a saved source's connection
edisyl data-sources rename <id> --name "<name>"
edisyl data-sources delete <id> --confirm

The connectors are postgres and snowflake. The credential must be read-only. edisyl does not restrict the SQL it runs. The permissions of the login you connect are the only limit. Grant SELECT only.

A Postgres config looks like this. port defaults to 5432. sslMode defaults to require and is one of disable, require, prefer, verify-ca or verify-full. The two verify- modes also take sslCert, a PEM-encoded CA certificate.

{"host": "db.example.com", "port": 5432, "username": "readonly", "password": "...", "sslMode": "require"}

A Snowflake config sets authMethod to password or keypair. account, username, warehouse and role are required either way.

{"authMethod": "password", "account": "xy12345.us-east-1", "username": "SVC_EDISYL", "password": "...", "warehouse": "COMPUTE_WH", "role": "ANALYST"}

For keypair, replace password with privateKey. This is a PEM-encoded PKCS#8 key. Its public key must be registered on the Snowflake user. Add privateKeyPassphrase only if the key is encrypted. Use a dedicated Snowflake user whose only role is the read-only role. Turn off secondary roles with ALTER USER <user> SET DEFAULT_SECONDARY_ROLES = ().

Both connectors use the field username, not user. The database is not part of the config. Pass it with --database. A database key inside the config is ignored.

Flag	Behavior
--config-file <path> / --config-json '<inline>'	Connector-specific JSON. Use exactly one of these two flags. The connector checks the shape on the server. A wrong key shows as a connector error, not a flag error.
--pack-id <id>	Attach to an existing pack instead of auto-creating one. Requires contribute access.
--name "<name>"	Required. The display name.
--database <db>	Required. The database to mount.
--schema <schema>	Limit the source to one schema.
--admit <table>,...	Admit only these tables on the first discovery. The other tables in the scope stay pending. Auto-add starts off. A table name can be as short as the scope allows: just the table under a schema, schema.table under a whole database, or the full db.schema.table. A table outside the scope makes create fail.
--no-auto-add-tables	Keep tables found later as pending. Without this flag, the daily refresh adds and enriches them.
--selection-rule <scope>=<identifier>	Limit the import. scope is schema or database. Repeat the flag for each rule.
--type <connector>	postgres or snowflake. Not used with --connection-id.
--connection-id <id>	Use an existing reusable connection for this data source instead of new credentials. Requires --database.

A common first-run mistake is to pass a schema that holds no tables. The import then fails with No tables found after introspection. This means the target was empty, not that the credentials were wrong. To check, read the output of edisyl connections databases <connection-id> and the message of the failed run.

test-connection returns { success: true, durationMs } on success, or { success: false, message } on failure. The message describes the problem.

create runs introspect, which lists the tables, and an import, which brings the tables in by name. It makes no LLM calls. enrich is the step that makes the source answerable. It studies every model to learn what the columns mean and how the tables join. It is also the manual resync. Run it when you want the catalog re-read now instead of at the next refresh. Until a model is studied, questions that depend on it are declined as though the data were absent. The daily refresh studies every model that has never been studied, and every model whose table changed. To study the whole source now, run enrich.

study starts one study for each semantic model built on the tables you pass. Use it to retry a failed study without restudying the whole source. A table is reported as skipped if it isn’t admitted, is outside the source’s scope, or hasn’t been imported yet. Import it first. To pass models instead of tables, see Study chosen models.

get shows the source’s scope, which is the set of tables it covers. It also shows what the daily refresh does with new tables. A source with schema or database rules covers tables created after it was connected. A source whose rules each point to a single table never gains new tables.

rename changes only the display name. Use it instead of deleting and recreating the source. Deleting a source also removes its imported models and their studies.

The daily refresh finds tables created later in the source’s scope. Manage them with these commands:

edisyl data-sources pending <id>                       # tables found and held back
edisyl data-sources admit <id> [<db.schema.table>...]  # import and study them (all pending, with no names); --no-study to skip the study
edisyl data-sources withdraw <id> <db.schema.table>    # take a table back out; its model is archived
edisyl data-sources auto-add <id> --on|--off           # add and enrich new tables daily, or hold them

Admitting a table imports it and studies it. To skip the study, pass --no-study. A table admitted with --no-study is in the catalog with only its column names. Questions that depend on it are declined as though the data were absent. Study it later with enrich.

withdraw takes a table out of the pack. Nothing queries it after that. Its semantic model is archived, together with the proven answers that depended on it. You cannot undo this. If you admit the table again, it is imported and studied from the start. The withdrawn table stays in the catalog as pending.

See Adding tables to a connected source.

To see the modeling status of a source, run edisyl calibrate status <pack> (see Calibrate). Run edisyl data-sources models <id> to list the models it has indexed.

Manage connections

CLI only

A connection holds provider credentials for the org. It is separate from any one data source. A SQL connection is used by data sources (data-sources create --connection-id). An API connection attaches directly to a pack.

edisyl connections list
edisyl connections get <connection-id>
edisyl connections test --provider <provider> --config-file <f>    # test unsaved credentials
edisyl connections create --provider <provider> --name "<name>" --config-file <f>
edisyl connections create --provider linear --name "<name>" --pack-id <id> --token-stdin
edisyl connections databases <connection-id>    # what a SQL connection can see
edisyl connections attach <connection-id> --pack-id <id>
edisyl connections update <connection-id> --config-file <f>   # replace credentials in place
edisyl connections rename <connection-id> --name "<name>"
edisyl connections delete <connection-id> --confirm

Providers are snowflake, postgres, github, and linear. SQL providers take the same --config-file / --config-json shapes as data-sources create. Linear takes a personal API key on --token-stdin. GitHub takes --installation-id. Edisyl staff set it up. See GitHub.

create and update test the credentials before they save them. A config that can’t connect is rejected, and the stored config does not change. update and rename keep the connection’s identity. Sources mounted on the connection keep their imported catalog.

connections list shows every connection in the organization. To see what one pack can query, use edisyl pack connections list <pack>.

Use --token-stdin and pipe the token in. The token then does not appear in shell history or a process listing.

printf '%s' "$LINEAR_API_KEY" | edisyl connections create \
  --provider linear --name "Tracker" --pack-id <pack-id> --token-stdin

Import tables into a pack

CLI only

edisyl import <pack> <data-source-id> [flags]

Bring a data source’s catalog into a pack. The command introspects the tables, syncs their models into the pack, and studies each model. The study teaches the pack what the model means.

edisyl import my_pack 3f2b1c40-8f2a-4a1e-9c33-2a9b6d0f1234
edisyl import my_pack <data-source-uuid> --no-study

Flag	Behavior
--no-study	Sync the schema only and skip studying. This costs nothing, but the pack learns nothing new. Questions that depend on an unstudied model are declined as though the data were absent.
-j, --json	Machine-readable output.

import creates an Action and returns immediately with its id. Each studied model runs as a child Action. Follow the whole tree with edisyl action watch <action-id>.

Calibration starts automatically after an import. See Calibrate. To study only some models, see Study chosen models. Connecting a new source imports its tables for you. See Connect and manage a data source.

Study chosen models

CLI only

edisyl study <pack> <data-source-id> <model-name> [<model-name>...] [flags]

Study one model, or a few, without restudying the whole source or the whole pack. Each study examines one model and adds to what the pack knows about it: descriptions, measures, dimensions, and relationships. Use it to retry a study that failed, or to learn more about the tables a question depends on.

edisyl study my_pack <data-source-uuid> analytics.public.fact_swaps
edisyl study my_pack <data-source-uuid> analytics.public.fact_swaps analytics.public.dim_users
edisyl study my_pack <data-source-uuid> analytics.public.dim_users --guidance "the churn columns are what we report on"

A model name is the fully qualified lowercase name the source indexed: database.schema.table. List them with edisyl data-sources models <data-source-id>. The CLI checks each name against the source before any study starts.

Flag	Behavior
--guidance "<text>"	What the studies should focus on, in plain language. Applies to every model you pass.
-j, --json	One model prints its Action. Several models print an array of Actions.

study starts one Action per model and returns immediately with each Action id. Follow one with edisyl action watch <action-id>, or list them all with edisyl action list --pack <pack> --type study.

In most packs, a study proposes its findings as learning candidates. Some packs study in the background instead. In those packs, the Action succeeds as soon as the background run starts, and no learning candidates open. The model changes when the run finishes. action watch ends when the run starts. Check the result afterwards with edisyl data-sources models <data-source-id>.

To study by table instead of by model, use edisyl data-sources study. To study every model on a source, run edisyl data-sources enrich <id>. To bring a source’s tables into a pack and study them all, run edisyl import. To calibrate the whole pack, run edisyl calibrate <pack>.

Rebuild a search index

CLI only

edisyl refresh <pack> <knowledge-base> [--mode full|rechunk]

Rebuild the search index for one of a pack’s knowledge bases. Retrieval then reflects the knowledge base’s current content. Pass the knowledge base’s slug or UUID.

edisyl refresh my_pack my-kb
edisyl refresh my_pack <kb-uuid> --mode rechunk

--mode	What it does
full	Default. Re-embed every stored chunk.
rechunk	Re-derive chunks from each document’s own text, then embed them. Search keeps working while it runs. It skips documents whose chunks are already current. If a run fails, running it again continues from where it stopped.

refresh creates an Action and returns immediately. Follow it with edisyl action watch <action-id>.