feat: add the ability to generate a config file

README.md

@@ -39,7 +39,16 @@ The package requires Python 3.14+ and ships a console script `odsbox-diff`.
 
 ## Quick start
 
-1. Copy one of the example configs from `configs/` and adjust it:
+1. Create a starter config:
+
+  ```powershell
+  uv run odsbox-diff create-config
+  ```
+
+  Default output is `./odsbox-diff.config.toml` with three use-case server
+  entries: `default` (basic), `production` (m2m), and `staging` (oidc).
+
+  Or copy one of the example configs from `configs/` and adjust it:
 
    - `config.example.toml` — basic auth (single or multiple servers)
    - `config.m2m.example.toml` — OAuth2 machine-to-machine
@@ -128,6 +137,16 @@ replacing them.
 | `-v`, `--verbose` | INFO logging with timestamps. |
 | `-q`, `--quiet` | Suppress all logging. |
 
+### `odsbox-diff create-config` (config scaffolding)
+
+| Flag | Description |
+| --- | --- |
+| `-o`, `--output` | Output path (default: `./odsbox-diff.config.toml`). |
+| `--force` | Overwrite output file if it already exists. |
+| `--single-auth {basic,m2m,oidc}` | Generate only one server section. |
+| `--with-queries` / `--no-queries` | Include or skip `queries.first` and `queries.second`. |
+| `--include-example-comments` / `--minimal` | Verbose guided output or compact output without comments. |
+
 ## Exit codes
 
 | Code | Meaning |
@@ -210,6 +229,9 @@ dump_diff_as_json("diff.json", diff)
 Either a single `[server]` table (stored internally as the `default` server) or
 one `[servers.<name>]` table per named server. Common fields:
 
+For single-server usage, `[servers.default]` is supported and behaves the same
+as `[server]`.
+
 | Field | Type | Notes |
 | --- | --- | --- |
 | `url` | string | ODS REST endpoint (required). |

configs/config.example.toml

@@ -2,26 +2,26 @@
 # Copy this file and adjust values for your environment.
 #
 # Usage (single server):
-#   uv run odsbox-diff --config config.toml -entity TestStep -id1 2 -id2 3
+#   uv run odsbox-diff --config config.example.toml -entity TestStep -id1 2 -id2 3
 #
 # Usage (compare across two named servers):
-#   uv run odsbox-diff --config config.toml -entity TestStep -id1 2 -id2 3 --server1 production --server2 staging
+#   uv run odsbox-diff --config config.example.toml -entity TestStep -id1 production:2 -id2 staging:3
 
 # ── Single server ────────────────────────────────────────────────────
-# Use [server] when comparing two instances on the same server.
-[server]
+# Use [servers.default] when comparing two instances on the same server.
+# No need to specify the server name in id declarations, e.g. -id1 2 -id2 3.
+[servers.default]
 url = "http://localhost:57481/api"
 verify_certificate = false          # set true for production with valid TLS
 method = "basic"
 username = "admin"
 # password = "admin"               # prefer keyring over plaintext!
 # To store in keyring:
-#   python -c "import keyring; keyring.set_password('odsbox-diff', 'http://localhost:57481/api:admin', 'admin')"
+#   keyring set odsbox-diff http://localhost:57481/api:admin
 
 # ── Multiple named servers ───────────────────────────────────────────
 # Use [servers.<name>] to define two or more servers.
-# Pick them at runtime with --server1 <name> --server2 <name>.
-# If only one server is defined below, --server1/--server2 are not required.
+# Pick them at runtime as prefix in the id declarations, e.g. -id1 production:2 -id2 staging:3.
 #
 # [servers.production]
 # url = "https://prod.example.com/api"

configs/config.m2m.example.toml

@@ -1,7 +1,7 @@
 # odsbox-diff configuration — M2M (machine-to-machine) authentication example
 #
 # Usage:
-#   uv run odsbox-diff --config config.m2m.toml -entity TestStep -id1 2 -id2 3
+#   uv run odsbox-diff --config config.m2m.example.toml -entity TestStep -id1 2 -id2 3
 
 # ── Server (connection + authentication combined) ────────────────────
 [server]
@@ -13,7 +13,7 @@ token_endpoint = "https://auth.example.com/realms/myrealm/protocol/openid-connec
 scope = ["machine2machine"]
 # client_secret is intentionally omitted — it will be retrieved from keyring.
 # To store in keyring:
-#   python -c "import keyring; keyring.set_password('odsbox-diff', 'https://auth.example.com/realms/myrealm/protocol/openid-connect/token:f0a8cec0-e980-48c4-9898-8a11f40da518', 'YOUR_SECRET')"
+#   keyring set odsbox-diff https://auth.example.com/realms/myrealm/protocol/openid-connect/token:f0a8cec0-e980-48c4-9898-8a11f40da518
 
 # ── Diff defaults ────────────────────────────────────────────────────
 [defaults]

configs/config.oidc.example.toml

@@ -1,7 +1,7 @@
 # odsbox-diff configuration — OIDC (interactive browser login) authentication example
 #
 # Usage:
-#   uv run odsbox-diff --config config.oidc.toml -entity TestStep -id1 2 -id2 3
+#   uv run odsbox-diff --config config.oidc.example.toml -entity TestStep -id1 2 -id2 3
 
 # ── Server (connection + authentication combined) ────────────────────
 [server]
@@ -19,7 +19,7 @@ webfinger_path_prefix = "/ods"        # optional, for non-standard WebFinger pat
 # authorization_endpoint = "https://auth.example.com/authorize"
 # token_endpoint = "https://auth.example.com/token"
 # client_secret is optional for OIDC; if needed, store it in keyring:
-#   python -c "import keyring; keyring.set_password('odsbox-diff', 'https://auth.example.com/token:14df520f-f6b0-4135-be1b-bff3f5cc474c', 'YOUR_SECRET')"
+#   keyring set https://auth.example.com/token:14df520f-f6b0-4135-be1b-bff3f5cc474c
 
 # ── Diff defaults ────────────────────────────────────────────────────
 [defaults]

docs/usage.md

@@ -39,6 +39,16 @@ environment:
 | `config.m2m.example.toml` | OAuth2 machine-to-machine |
 | `config.oidc.example.toml` | OIDC (interactive browser login) |
 
+Or generate a new starter config directly:
+
+```powershell
+uv run odsbox-diff create-config
+```
+
+By default this writes `./odsbox-diff.config.toml` with three use-case server
+entries (`default=basic`, `production=m2m`, `staging=oidc`) and two query placeholders
+(`queries.first`, `queries.second`).
+
 ### Keyring secrets
 
 Rather than storing secrets in the config file, store them in your OS keyring
@@ -196,6 +206,27 @@ uv run odsbox-diff collect `
 
 ---
 
+## CLI: Create Config
+
+The `create-config` subcommand creates a new TOML config from the three example
+files in `configs/`.
+
+```powershell
+uv run odsbox-diff create-config
+```
+
+### Create-config flags
+
+| Flag | Description |
+| --- | --- |
+| `-o`, `--output` | Output path (default: `./odsbox-diff.config.toml`). |
+| `--force` | Overwrite output file if it already exists. |
+| `--single-auth {basic,m2m,oidc}` | Generate only one server section (`default`/`production`/`staging`). |
+| `--with-queries` / `--no-queries` | Include or skip `queries.first` and `queries.second`. |
+| `--include-example-comments` / `--minimal` | Verbose guided output or compact output without comments. |
+
+---
+
 ## Exit Codes
 
 | Code | Meaning |
@@ -214,6 +245,9 @@ uv run odsbox-diff collect `
 Either a single `[server]` table or one `[servers.<name>]` table per named
 server.
 
+For single-server usage, `[servers.default]` is also valid and behaves like
+`[server]`.
+
 | Field | Type | Default | Notes |
 | --- | --- | --- | --- |
 | `url` | string | — | ODS REST endpoint (required). |

src/odsbox_diff/__init__.py

@@ -8,7 +8,7 @@
     diff_file_to_server,
     diff_server_to_server,
 )
-from .diff import collect_ods_test, diff_ods_tests
+from .diff import collect_ods_test, create_config_file, diff_ods_tests
 from .ods_diff_hierarchy import (
     collect,
     diff_dictionaries,
@@ -20,6 +20,7 @@
 __all__ = [
     "collect_ods_test",
     "collect_to_file",
+    "create_config_file",
     "diff_file_to_file",
     "diff_file_to_server",
     "diff_ods_tests",