docs: add overview section and document download command

.github/workflows/check.yml

@@ -0,0 +1,25 @@
+name: Check
+
+on:
+  pull_request:
+  push:
+    branches-ignore:
+      - master
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.9"
+
+      - run: uv sync --group dev
+
+      - run: uv run ruff check .
+
+      - run: uv run pytest

README.md

@@ -1,6 +1,31 @@
 Populate Gitlab Project Variables from .env file
 =================================================
 
+## Overview
+
+A command-line tool for managing a Gitlab project's CI/CD variables, scoped to a
+Gitlab [environment](https://docs.gitlab.com/ee/ci/environments/) (e.g. `uat`,
+`production`). It talks to the Gitlab API using a personal access token and lets
+you move variables between a local `.env` file and Gitlab in both directions.
+
+It provides four commands:
+
+- `write` — read a local `.env` file and create or update the matching
+  project variables in the given environment scope. Supports `--include` /
+  `--exclude` filtering and `--mask` to mask values whose key contains the
+  substring `KEY`, `SECRET`, or `TOKEN` (e.g. `APP_KEY`, `PUBLIC_KEY`,
+  `AUTH_TOKEN` will all be masked). Masking is one-way: an already-masked
+  variable is never un-masked by this tool.
+- `list` — print the variables for an environment in a table. Masked values are
+  hidden unless you pass `--sensitive`.
+- `get` — print the variables for an environment, optionally appending them to a
+  `<scope>.env` file with `--export`.
+- `download` — write an environment's variables to a `<environment>.env` file,
+  prompting before overwriting an existing file.
+
+All commands target both the requested environment and globally-scoped (`*`)
+variables. Requires a `GITLAB_TOKEN` environment variable.
+
 ## Install
 
 Install as a global user tool (isolated environment, command on your PATH):
@@ -56,3 +81,9 @@ populate-secrets-gitlab write \
 ```shell
 populate-secrets-gitlab get --environment uat --gitlab-host gitlab.example.com --project my-group/my-project --export
 ```
+
+### Download variables to an .env file
+
+```shell
+populate-secrets-gitlab download --environment uat --gitlab-host gitlab.example.com --project my-group/my-project --output-dir .
+```

src/populate_secrets_gitlab/app.py

@@ -16,7 +16,7 @@
 logging.basicConfig(
         level=logging.INFO,
         format='%(asctime)s %(levelname)s\t%(message)s',
-        datefmt='%Y-%m-%d_%H:%M:%S.%s',
+        datefmt='%Y-%m-%d_%H:%M:%S',
         handlers=[
             logging.StreamHandler()
         ],

src/populate_secrets_gitlab/gitlab_server.py

@@ -3,5 +3,3 @@
 
 def gitlab_client(gitlab_host, gitlab_token):
     return gitlab.Gitlab(util.prepare_gitlab_host(gitlab_host), private_token=gitlab_token)
-
-