Persistent analytical data for agents.

The agent installs the CLI and runs tablemere login. The CLI prints a link with a code, opens the browser when there is one, and waits up to fifteen minutes; the agent shows the person the link. --level read asks for read only, --name names the connection, --catalog picks one; the default is the organisation's default catalog with read and write.

$ curl -fsSL https://tablemere.com/install.sh | sh
$ tablemere login
# Open https://tablemere.com/app/device?user_code=XXXX-XXXX
# and approve the connection in your browser (code XXXX-XXXX).
# … waiting (up to 15 minutes)

The person opens the link. With no account yet, the same page offers to create one: name, email, organisation, the link in the mail, a password, and the Terms; the code survives. Then a consent screen names the machine, the catalog and the access asked for, which they may lower to read. On approval the CLI receives the key of a new agent named after the machine, saves it to ~/.config/tablemere/credentials.json and never shows it. Revoke it any time under Connections & tokens. A key can also be minted by hand for a machine without a browser.

# the CLI, once approved:
Connected to My warehouse (read and write) as laptop.
Saved to ~/.config/tablemere/credentials.json.
# by hand, from a person's terminal, key shown once:
$ tablemere agent create --name reporter \
    --grant <warehouse_id>:write

Before touching anything, the agent reads its identity, its limits and the tables that exist. Output is JSON whenever stdout is not a terminal, so a script parses the same thing a person reads. GET /v1/usage lists every limit, the current value and the headroom: a limit is never met by failing.

$ tablemere whoami
# who am I, my limits, what I hold on each catalog
$ tablemere usage
# storage 5 GB, catalogs 3/project, tables 50, namespaces 10,
# objects 50,000, commits 20,000/month, each with its headroom
$ tablemere table list --catalog lake
$ tablemere table get --catalog lake --namespace demo --name cities
# schema, format version, snapshots, rows, data_files

One command returns the paste-ready SQL for the agent's DuckDB (1.5.5 or newer), with the catalog's credential inside. The engine exchanges it for catalog tokens (900 s) and per-table storage sessions itself. ATTACH the bare bucket name: 'w-<uuid>' is read-write, the s3:// form attaches read-only. The recipe's fourth statement, an S3 secret for inspecting the bucket, is not needed for tables.

$ tablemere connect --catalog lake --engine duckdb
INSTALL iceberg; LOAD iceberg; INSTALL httpfs; LOAD httpfs;
CREATE SECRET tablemere (TYPE ICEBERG,
  CLIENT_ID '<client_id>', CLIENT_SECRET '<client_secret>',
  OAUTH2_SERVER_URI 'https://catalog.tablemere.eu/v1/oauth/tokens');
ATTACH 'w-<warehouse_uuid>' AS lake (TYPE ICEBERG,
  ENDPOINT 'https://catalog.tablemere.eu', SECRET tablemere);

Importing Parquet is one statement, from a local file or a URL; namespaces are schemas. Measured against the service: a million rows, 18 MB of Parquet, in about 2.3 s from a laptop, three data files, one commit. The result is an Iceberg table, format version 2.

-- a new table, from a file or a URL
CREATE TABLE lake.demo.events AS
  SELECT * FROM read_parquet('events.parquet');
-- into a table that exists
INSERT INTO lake.demo.events
  SELECT * FROM read_parquet('more-events.parquet');
COPY lake.demo.events FROM 'more-events.parquet' (FORMAT PARQUET);
-- namespaces are schemas
CREATE SCHEMA lake.staging;

From here on it is DuckDB. The engine lists the table through the catalog, receives storage credentials scoped to that table, and reads the Parquet files from s3.tablemere.eu itself. Tablemere sees the catalog call and the object reads; it never sees a result set.

SELECT date_trunc('day', event_time) AS day,
       count(*) AS events,
       avg(value) AS mean_value
FROM lake.demo.events
GROUP BY 1 ORDER BY 1;

A saved result is a table another session can open. One CTAS and the summary lives next to the source, versioned and maintained like it. CTAS makes every column optional; when identifier fields, required columns or partitioning matter, create the table first with tablemere table create --column name:type[:required][:identifier], then INSERT.

CREATE TABLE lake.demo.daily_summary AS
  SELECT date_trunc('day', event_time) AS day,
         count(*) AS events, avg(value) AS mean_value
  FROM lake.demo.events GROUP BY 1;

-- a later session, another agent, a colleague:
SELECT * FROM lake.demo.daily_summary ORDER BY day DESC LIMIT 7;

Access is a grant per catalog: read or write, to a member or to an agent key. A read holder's connect carries the read-only identity; the catalog refuses its commits and the store its writes. Colleagues join by invitation, or automatically once your organisation has claimed its email domain.

$ tablemere org invite --email colleague@company.com --role member
# the invitation token is returned once and mailed
$ tablemere catalog grant --catalog lake \
    --principal <principal_id> --level read
$ tablemere agent create --name analyst --grant <warehouse_id>:read
$ tablemere catalog grants --catalog lake
# who holds read or write, and how: admin, membership, creator, grant

A person's lost key is replaced by a code to their email, never recovered; an agent's lost key is revoked and a new agent created. The audit log answers who did what, for 400 days. Snapshot history is bounded: maintenance keeps 20 snapshots and 7 days per table, so time travel reaches back that far and no further.

$ tablemere recover --email you@company.com
$ tablemere recover --email you@company.com --code 123456 --save
# a NEW key; earlier keys keep working until revoked
$ tablemere agent revoke --agent-id <agent_id>
# every key of that agent stops at once
$ tablemere audit --since 7d --action credentials.vend
$ tablemere catalog rotate --catalog lake
# new catalog credentials; old tokens refused now, vended
# storage sessions run out within 900 s; fetch a fresh recipe