Command line

Installing the library adds the gwenlake command, its shorter alias gwl, and gwenlake-train.

`gwenlake`

The same resources as the Python client, in noun-verb form:

gwenlake [--profile NAME] [--api-key KEY] [--base-url URL] [--json] <resource> <command> [arguments]

Listings print as a table; --json prints what the API answered, ready for jq. gwenlake --help lists the resources, gwenlake <resource> --help the commands of one.

A first look
SQL and exports
Builds and schedules
Code

gwenlake me                                   # who the credentials belong to
gwenlake projects list
gwenlake datasets list --project fleetsight
gwenlake datasets summary fleetsight.aisdk_positions
gwenlake search ais --project fleetsight --type dataset

gwenlake sql "SELECT zone, count(*) FROM 'fleetsight.aisstream_positions' GROUP BY 1"
gwenlake sql --file report.sql --json
gwenlake sql "SELECT * FROM 'fleetsight.aisdk_vessels'" --out vessels.parquet
gwenlake datasets export fleetsight.aisdk_positions --out positions.csv --where "zone = 'brest'"
gwenlake sql "SELECT * FROM 'fleetsight.aisdk_vessels'" -o - --format parquet > vessels.parquet

gwenlake builds run fleetsight.aisstream_vessels --wait          # each step on stderr as it settles
gwenlake builds run fleetsight.aisstream_vessels --dry-run       # the builds it would run; starts nothing
gwenlake builds run fleetsight.aisdk_vessels fleetsight.aisdk_positions --follow
gwenlake builds retry build.58d2bddbad62 --wait                  # its target again, on its data branch
gwenlake builds propagate fleetsight.aisdk_positions --wait      # what is downstream of it
gwenlake builds list --project fleetsight --status failed --since 1d
gwenlake builds logs build.58d2bddbad62 --follow                 # new lines until the build ends
gwenlake builds cancel build.58d2bddbad62 --batch                # the rest of its batch too
gwenlake schedules list --project fleetsight
gwenlake schedules create --project fleetsight --name "Nightly refresh" \
    --cron "0 6 * * *" --time-zone Europe/Paris --target fleetsight.aisdk_quality_by_day
gwenlake schedules update res.schedule.… --cron "*/15 * * * *" --enable

gwenlake repositories list --project fleetsight
gwenlake repositories scan res.repository.… --wait        # re-read the producers, sync the lineage
gwenlake transforms list --project fleetsight
gwenlake transforms set-parameters res.transform.… listen_seconds=600 api_key=…
gwenlake queries get res.sql-query.…                        # prints the SQL
gwenlake lineage fleetsight.aisdk_vessels --direction upstream

Names

A dataset is named <project>.<dataset>, with the slugs the platform shows (fleetsight.aisdk_positions), or by its id (res.dataset.…). A project is named by its slug or its id. Other resources (builds, schedules, transforms, repositories, queries) are named by id; their list commands show the ids.

Resources and commands

Resource	Commands
`me`	who the credentials belong to
`projects`	`list`, `get`, `create`, `delete`
`datasets`	`list`, `get`, `summary`, `create`, `update`, `delete`, `empty`, `delete-rows`, `branches`, `export`
`files`	`list`, `upload` (`--mode APPEND\|SNAPSHOT\|UPSERT`, `--path`, `--branch`), `download`, `delete`
`sql`	run a statement; `--limit` when printing, `--out file` (`-o`) to write the whole result (`.parquet`, `.csv`, `.json`, `.jsonl`), `-o - --format …` to write it to stdout, `--file` to read the statement from a file, `--mode spark` for the Spark engine
`builds`	`run` (one or more datasets; `--target-only`, `--branch`, `--wait`, `--follow`, `--dry-run`), `retry`, `propagate`, `list` (`--target`, `--project`, `--status`, `--trigger`, `--since`, `--limit`), `get`, `logs` (`--tail`, `--follow`), `wait`, `cancel` (`--batch`)
`schedules`	`list`, `get`, `create`, `update`, `delete`, `trigger`
`transforms`	`list`, `get`, `set-parameters`, `execute`, `functions`
`repositories`	`list`, `get`, `scan`, `tree`
`queries`	`list`, `get`, `execute`
`lineage`	the graph around a dataset, a project or any resource id
`connections`	`list`, `get`, `files`
`search`	resources by name, optionally of one type
`models`	`list` (inference models), `ml` (the catalog’s ML models)
`organizations`	`list`, `members`
`api-keys`	`list`, `create`, `delete`
`config`	`path`, `list`, `set-profile`, `remove-profile`

Destructive commands (delete, empty) ask for confirmation; pass --yes in a script.

Builds

builds run builds a dataset and every producer upstream of it, whether its data changed or not; --target-only builds the dataset alone. With --wait, each step is printed on stderr as it settles, with its duration, and the table of the batch on stdout once it is over:

2 builds: fleetsight.aisdk_raw -> fleetsight.aisdk_positions
[1/2] fleetsight.aisdk_raw RUNNING
[1/2] fleetsight.aisdk_raw SUCCESS (2m13s)
[2/2] fleetsight.aisdk_positions RUNNING
[2/2] fleetsight.aisdk_positions FAILED (41s)
transform exited with code 1
-- last 20 log lines of build.… --
…
to run it again: gwenlake builds retry build.…

A failed step prints its error and the end of its log, and the waiting stops there: the platform cancels the steps after it. --follow (-f) prints each build’s log as it runs, and builds logs --follow prints one build’s log until it ends. builds run, retry and propagate with --wait or --follow, builds wait and builds logs --follow exit with status 1 when a build failed or was cancelled, so a script can stop there.

--dry-run asks the platform for the plan a run would follow (the steps in order, what each one waits for, the other datasets a step rewrites) and starts nothing. It is refused where the build would be.
Several datasets give one batch each; a dataset the platform refuses does not stop the others.
retry builds the target of a finished build again, on the same data branch: retrying the last build of a failed batch runs the batch again.
propagate builds again every dataset downstream of one, not the dataset itself; see Workflows.
cancel --batch cancels every build of the batch still pending or running, the last steps first.
list shows each target as <project>.<dataset> and each build’s duration. --project keeps the builds of a project’s datasets and models, --trigger those of one kind (manual, schedule, event), --since those started after a date, a time or an age (2026-11-01, 2026-11-01T08:00, 90m, 6h, 3d).

Credentials

The command resolves its API key in the same order as the client:

--api-key;
--profile NAME, a section of the credentials file (or GWENLAKE_PROFILE);
GWENLAKE_API_KEY in the environment — a .env file in the current directory is read first, which is how a project keeps its key next to its code;
the default profile of the credentials file.

The credentials file is ~/.gwenlake/credentials (%APPDATA%\.gwenlake\credentials on Windows), an INI file with one section per profile. gwenlake config manages it without opening an editor:

gwenlake config path                                        # where the file is
gwenlake config set-profile default --token sk-...
gwenlake config set-profile acme --token sk-... --base-url https://atlas.acme.example/v1
gwenlake config list                                        # the profiles, secrets masked
gwenlake config remove-profile acme

~/.gwenlake/credentials

[default]
token = sk-...

[acme]
token = sk-...
base_url = https://atlas.acme.example/api/v1

[service]
client_id = ...
client_secret = ...
hostname = https://auth.gwenlake.com

A profile holds a static token (an API key) or an OAuth2 client_id and client_secret (see Authentication), and may carry the endpoint it is for as base_url (or host for a bare host). hostname is the OAuth server, not the API. The file is written readable by you only.

Endpoints

Short name	URL	Serves
`api` (default)	`https://api.gwenlake.com/v1`	the Gwenlake APIs and the Atlas catalog
`atlas`	`https://atlas.gwenlake.com/api/v1`	the same API, as the Atlas application serves it
a tenant	`https://atlas.acme.example/v1` or `/api/v1`	a platform deployed for one client

gwenlake config endpoints prints this table with the endpoint in use. The endpoint is chosen, in order of precedence, by:

--base-url on the command: a short name (--base-url atlas), a host (--base-url atlas.acme.example) or a URL;
the GWENLAKE_BASE_URL environment variable;
the base_url (or host) key of the selected profile;
api.

A profile that carries both its token and its base_url makes a tenant one option away: gwenlake --profile acme datasets list. A deployment serves the API under a version prefix: an API host under /v1 (https://api.gwenlake.com/v1), an Atlas application host under /api/v1 (https://atlas.gwenlake.com/api/v1, or a tenant’s own host). The command completes what is missing: a bare host gets /v1, a host with /api gets /api/v1, any other path is used as given (http://localhost:8000/v1). Since a tenant’s host may serve the API either way, gwenlake config set-profile --base-url atlas.acme.example probes both and stores the one that answers; --no-probe stores the URL as completed. A URL that answers the application’s HTML page instead of JSON is reported as such.

`gwenlake-train`

Finds the function decorated with @train in a project and runs it. This is what the GPU pool runs, and what you run locally to test a training.

gwenlake-train --list                 # show what was found and stop
gwenlake-train                        # run it
gwenlake-train --steps 500 --eval-every 50
gwenlake-train --function fit         # when the project holds several
gwenlake-train --path ./ml            # project root to search

--steps and --eval-every override the defaults set on the decorator without touching the code. See Models.

Get started

Concepts

Workspace

Data

Code

Build

Models

Inference

Agents

Client

Changelog

`gwenlake`

Names

Resources and commands

Builds

Credentials

Endpoints

`gwenlake-train`

​gwenlake

​Names

​Resources and commands

​Builds

​Credentials

​Endpoints

​gwenlake-train

`gwenlake`

Names

Resources and commands

Builds

Credentials

Endpoints

`gwenlake-train`