Sharing semantic layers¶

Semantic layers are shared the way Agent Skills are: as folders in git repositories, installed with one command. The command, semantic-layers, is a Python tool run with uv — nothing to install beyond uv.

Installing¶

uvx semantic-layers add SynaLinks/semantic-layers              # every layer of the repository
uvx semantic-layers add SynaLinks/semantic-layers --layer sales
uvx semantic-layers add SynaLinks/semantic-layers --list       # its layers and their definitions
uvx semantic-layers add https://git.example.com/data/layer.git          # any git URL
uvx semantic-layers add ./path/to/layers                                # a local folder

add fetches the source, copies the layer folders into .agents/layers/, verifies each with synalog, and records them in semantic-layers-lock.json (at the project's root; ~/.agents/semantic-layers-lock.json with --global). Commit the lock file so teammates and CI resolve the same layers.

What add guarantees:

• Nothing unverified lands. Every layer is checked with synalog before the copy; if anything fails, nothing is installed.
• Your tables stay yours. Installing or updating a layer you already connected keeps its tables and its connection: only its concepts and rules are replaced, and they must verify against your tables — a table or column your database lacks is listed.
• No silent overwrite. A layer folder you wrote or changed is refused unless you pass --force.

Connecting¶

connect runs inside a layer — the folder with its layer.toml:

cd .agents/layers/sales
uvx semantic-layers connect psql host=db.example.com database=sales user=analyst password=...

This writes the connection into layer.toml (the fields, keeping its [project]), the password into .env, and .env into .gitignore (see Connection), then generates one file per table of the database with synalog introspect, keeping the descriptions and keywords already written. A table the layer has but the database doesn't is kept and reported, since definitions may still import it. Then the layer is checked: a concept or rule using a table or column your database lacks is listed, and so is an assertion its data violates.

Then any definition runs from the layer's folder:

cd .agents/layers/sales
uvx semantic-layers run ActiveCustomer      # in the layer's folder; elsewhere: run sales/ActiveCustomer

Publishing¶

Start a layer project with init, giving the layer's name — its folder — and asked for its description:

$ uvx semantic-layers init sales
Description (what the layer is about): Orders and customers: revenue, active customers.

Without a name, the layer is set up in the current folder, named after it (an empty repository you cloned, say). A coding agent or a script, with no terminal to answer in, passes the description with -d:

uvx semantic-layers init sales -d "Orders and customers: revenue, active customers."

sales/
├── tables/         # generated by connect
├── concepts/
├── rules/
├── layer.toml      # its name and description; the database, written by connect
├── .gitignore      # .env (the secrets), bigquery-credentials.json
└── README.md       # what the layer is, how to install and develop it

The name is lowercase letters, numbers and hyphens. The description, required, says what the layer is about. Both go in layer.toml's [project], which add --list and list show. init also runs git init when the folder isn't in a repository yet, and never overwrites a file. A named folder that exists and is not empty is refused unless you pass --force. Inside the project, connect it with semantic-layers connect psql host=... user=... and check it with semantic-layers check ..

A layer is published by pushing its folder to a git repository. A repository is either one layer — tables/, concepts/, rules/ at its root, named after the repository — or several, one folder each, at its root or under layers/ or .agents/layers/:

semantic-layers/layers/
├── sales/
│   ├── tables/
│   ├── concepts/
│   └── rules/
└── support/
    ├── tables/
    └── rules/

The secrets never travel: .gitignore keeps .env out. layer.toml does, so a team shares one database by name; the tables do too, and that is the point — they tell whoever installs the layer which data it expects.

Keeping up¶

uvx semantic-layers list      # the installed layers: where they came from, whether you changed them, whether they are connected
uvx semantic-layers update    # bring them to their source's latest version
uvx semantic-layers check     # verify every layer with synalog — or one: check sales
uvx semantic-layers search 'churn|retention'   # find definitions by name, keywords and description (a regex)

update never overwrites a layer you modified: it keeps it and says so.

Every command and its options: CLI. How coding agents are told about the layers: Coding agents.