ttlama-cli 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. ttlama_cli-0.1.0/LICENSE +71 -0
  2. ttlama_cli-0.1.0/PKG-INFO +310 -0
  3. ttlama_cli-0.1.0/README.md +281 -0
  4. ttlama_cli-0.1.0/pyproject.toml +46 -0
  5. ttlama_cli-0.1.0/setup.cfg +4 -0
  6. ttlama_cli-0.1.0/src/ttlama_cli/__init__.py +0 -0
  7. ttlama_cli-0.1.0/src/ttlama_cli/__main__.py +6 -0
  8. ttlama_cli-0.1.0/src/ttlama_cli/api_client.py +221 -0
  9. ttlama_cli-0.1.0/src/ttlama_cli/cli.py +71 -0
  10. ttlama_cli-0.1.0/src/ttlama_cli/commands/__init__.py +256 -0
  11. ttlama_cli-0.1.0/src/ttlama_cli/commands/admin/__init__.py +22 -0
  12. ttlama_cli-0.1.0/src/ttlama_cli/commands/admin/devices.py +300 -0
  13. ttlama_cli-0.1.0/src/ttlama_cli/commands/admin/leases.py +244 -0
  14. ttlama_cli-0.1.0/src/ttlama_cli/commands/admin/profiles.py +328 -0
  15. ttlama_cli-0.1.0/src/ttlama_cli/commands/admin/users.py +460 -0
  16. ttlama_cli-0.1.0/src/ttlama_cli/commands/auth.py +469 -0
  17. ttlama_cli-0.1.0/src/ttlama_cli/commands/backend/__init__.py +18 -0
  18. ttlama_cli-0.1.0/src/ttlama_cli/commands/backend/openvpn/__init__.py +0 -0
  19. ttlama_cli-0.1.0/src/ttlama_cli/commands/backend/openvpn/peers.py +0 -0
  20. ttlama_cli-0.1.0/src/ttlama_cli/commands/backend/wireguard/__init__.py +18 -0
  21. ttlama_cli-0.1.0/src/ttlama_cli/commands/backend/wireguard/peers.py +282 -0
  22. ttlama_cli-0.1.0/src/ttlama_cli/commands/config.py +350 -0
  23. ttlama_cli-0.1.0/src/ttlama_cli/commands/user/__init__.py +29 -0
  24. ttlama_cli-0.1.0/src/ttlama_cli/commands/user/devices.py +214 -0
  25. ttlama_cli-0.1.0/src/ttlama_cli/commands/user/get.py +95 -0
  26. ttlama_cli-0.1.0/src/ttlama_cli/commands/user/leases.py +223 -0
  27. ttlama_cli-0.1.0/src/ttlama_cli/commands/user/profiles.py +84 -0
  28. ttlama_cli-0.1.0/src/ttlama_cli/config_store.py +109 -0
  29. ttlama_cli-0.1.0/src/ttlama_cli/drivers/__init__.py +19 -0
  30. ttlama_cli-0.1.0/src/ttlama_cli/drivers/_common.py +116 -0
  31. ttlama_cli-0.1.0/src/ttlama_cli/drivers/openvpn.py +59 -0
  32. ttlama_cli-0.1.0/src/ttlama_cli/drivers/wireguard.py +165 -0
  33. ttlama_cli-0.1.0/src/ttlama_cli/exc.py +78 -0
  34. ttlama_cli-0.1.0/src/ttlama_cli/objects/__init__.py +18 -0
  35. ttlama_cli-0.1.0/src/ttlama_cli/objects/requests.py +65 -0
  36. ttlama_cli-0.1.0/src/ttlama_cli/token_store.py +85 -0
  37. ttlama_cli-0.1.0/src/ttlama_cli/utils.py +30 -0
  38. ttlama_cli-0.1.0/src/ttlama_cli.egg-info/PKG-INFO +310 -0
  39. ttlama_cli-0.1.0/src/ttlama_cli.egg-info/SOURCES.txt +53 -0
  40. ttlama_cli-0.1.0/src/ttlama_cli.egg-info/dependency_links.txt +1 -0
  41. ttlama_cli-0.1.0/src/ttlama_cli.egg-info/entry_points.txt +2 -0
  42. ttlama_cli-0.1.0/src/ttlama_cli.egg-info/requires.txt +14 -0
  43. ttlama_cli-0.1.0/src/ttlama_cli.egg-info/top_level.txt +1 -0
  44. ttlama_cli-0.1.0/tests/test_admin_devices_commands.py +334 -0
  45. ttlama_cli-0.1.0/tests/test_admin_leases_commands.py +230 -0
  46. ttlama_cli-0.1.0/tests/test_admin_profiles_commands.py +262 -0
  47. ttlama_cli-0.1.0/tests/test_admin_users_commands.py +359 -0
  48. ttlama_cli-0.1.0/tests/test_api_client.py +230 -0
  49. ttlama_cli-0.1.0/tests/test_auth_commands.py +679 -0
  50. ttlama_cli-0.1.0/tests/test_cli.py +503 -0
  51. ttlama_cli-0.1.0/tests/test_config_store.py +52 -0
  52. ttlama_cli-0.1.0/tests/test_global_config_commands.py +115 -0
  53. ttlama_cli-0.1.0/tests/test_token_store.py +48 -0
  54. ttlama_cli-0.1.0/tests/test_user_commands.py +160 -0
  55. ttlama_cli-0.1.0/tests/test_user_resource_commands.py +259 -0
@@ -0,0 +1,71 @@
1
+ # Apache License
2
+
3
+ English | [Français](./docs/LICENSE.fr.md)
4
+
5
+ Version 2.0, January 2004
6
+ <http://www.apache.org/licenses/>
7
+
8
+ ## TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
9
+
10
+ ### 1. Definitions
11
+
12
+ "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
13
+
14
+ "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
17
+
18
+ "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
19
+
20
+ "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
21
+
22
+ "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
23
+
24
+ "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
25
+
26
+ "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
27
+
28
+ "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
29
+
30
+ "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
31
+
32
+ ### 2. Grant of Copyright License
33
+
34
+ Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
35
+
36
+ ### 3. Grant of Patent License
37
+
38
+ Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
39
+
40
+ ### 4. Redistribution
41
+
42
+ You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
43
+
44
+ a. You must give any other recipients of the Work or Derivative Works a copy of this License; and
45
+ b. You must cause any modified files to carry prominent notices stating that You changed the files; and
46
+ c. You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
47
+ d. If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
48
+
49
+ You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
50
+
51
+ ### 5. Submission of Contributions
52
+
53
+ Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
54
+
55
+ ### 6. Trademarks
56
+
57
+ This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
58
+
59
+ ### 7. Disclaimer of Warranty
60
+
61
+ Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
62
+
63
+ ### 8. Limitation of Liability
64
+
65
+ In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
66
+
67
+ ### 9. Accepting Warranty or Additional Liability
68
+
69
+ While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
70
+
71
+ END OF TERMS AND CONDITIONS
@@ -0,0 +1,310 @@
1
+ Metadata-Version: 2.4
2
+ Name: ttlama-cli
3
+ Version: 0.1.0
4
+ Summary: Interface en ligne de commande pour TTL-LAMa, Time To Live - Lease Access Management
5
+ Author-email: "Rémi Verschuur|rverschuur@audit-io.fr|" <rverschuur@audit-io.fr>
6
+ Maintainer-email: Rémi Verschuur <rverschuur@audit-io.fr>
7
+ License-Expression: Apache-2.0
8
+ Project-URL: Repository, https://github.com/remiv1/TTL-LAMa-CLI
9
+ Keywords: TTL-LAMa,CLI
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Requires-Python: >=3.12
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: typer<1,>=0.27
17
+ Requires-Dist: platformdirs<5,>=4
18
+ Requires-Dist: requests<3,>=2
19
+ Requires-Dist: keyring<26,>=25
20
+ Requires-Dist: rich<16,>=15
21
+ Requires-Dist: pyyaml<7,>=6
22
+ Provides-Extra: test
23
+ Requires-Dist: pytest<10,>=9; extra == "test"
24
+ Requires-Dist: pytest-cov<8,>=7; extra == "test"
25
+ Provides-Extra: release
26
+ Requires-Dist: build<2,>=1; extra == "release"
27
+ Requires-Dist: twine<8,>=7; extra == "release"
28
+ Dynamic: license-file
29
+
30
+ # TTL-LAMa CLI
31
+
32
+ English | [Français](https://github.com/remiv1/TTL-LAMa-CLI/blob/main/docs/README.fr.md)
33
+
34
+ [![Python 3.12+](https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
35
+ [![Typer](https://img.shields.io/badge/CLI-Typer-009688)](https://typer.tiangolo.com/)
36
+ [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://github.com/remiv1/TTL-LAMa-CLI/blob/main/LICENSE)
37
+ ![Coverage](https://img.shields.io/badge/Coverage-77%25-yellow)
38
+
39
+ [![Logo](https://github.com/remiv1/TTL-LAMa/blob/main/docs/img/logo_300ppp.png)](https://github.com/remiv1/TTL-LAMa/blob/main/docs/img/logo_300ppp.png)
40
+
41
+ `ttlama` is the command-line interface for TTL-LAMa (Time-to-Live Lease Administration Manager). It lets users and administrators interact with a TTL-LAMa instance through its HTTP API, without relying on the web interface.
42
+
43
+ The CLI lives in the `cli/` directory and can evolve independently of the server. TTL-LAMa manages temporary network access as leases; the CLI is neither a VPN client nor a general-purpose network administration tool.
44
+
45
+ ## Project status
46
+
47
+ The CLI is under development. It provides server configuration, internal and OIDC authentication, self-service and administrative resource management, global configuration operations, and local WireGuard peer commands. The root command also provides `--version` (`-v`).
48
+
49
+ | Group | Available commands | Planned commands |
50
+ | --- | --- | --- |
51
+ | `config` | `set-server` | — |
52
+ | `auth` | `login internal`, `login oidc`, `logout`, `password-chg`, `status` | — |
53
+ | `user` | `get`, `profiles ls`, `profiles get`, `devices ls/get/add/delete`, `leases ls/get/create/revoke` | — |
54
+ | `global-config` | `get`, `diff`, `validate`, `apply` | — |
55
+ | `admin users` | `ls`, `get`, `create`, `update`, `delete`, `assign`, `unassign` | — |
56
+ | `admin devices` | `ls`, `get`, `update`, `block`, `delete` | — |
57
+ | `admin leases` | `ls`, `get`, `revoke` | — |
58
+ | `admin profiles` | `ls`, `get`, `create`, `update`, `delete` | — |
59
+ | `backend wg leases` | `ls`, `get`, `apply`, `delete` | — |
60
+ | `backend openvpn leases` | — | `ls`, `get`, `apply`, `delete` |
61
+
62
+ The `backend wg leases` commands inspect or mutate a local WireGuard interface; they do not provide scheduled reconciliation with the server. See the [command reference](docs/cli-reference.md) for exact arguments and input requirements.
63
+
64
+ Administrators can list leases using any combination of `--user`, `--device`, `--profile`, and `--status` (`active`, `expired`, or `revoked`). `get` displays the complete lease, including its derived status and lifecycle timestamps. `revoke` asks for confirmation before revoking the lease; its history is retained.
65
+
66
+ ```bash
67
+ ttlama admin leases ls --status active --yaml
68
+ ttlama admin leases get --lease 73 --json
69
+ ttlama admin leases revoke --lease 73
70
+ ```
71
+
72
+ ### Global configuration
73
+
74
+ `ttlama global-config get` reads the server's application YAML document;
75
+ `--json` and `--yaml` emit the raw document structure. Direct secret values are
76
+ shown as `[REDACTED]`. `diff --file` compares a local JSON or YAML candidate
77
+ with the current file, compares redacted secrets on the server, and never prints
78
+ direct secret values; `--check-all` also lists unchanged values.
79
+ `validate --file` asks the server to validate a candidate without writing it.
80
+ `apply --file` displays the changes and asks for confirmation; `--dry-run`
81
+ validates and displays the diff without applying it.
82
+
83
+ This group writes only the application configuration file selected by the
84
+ server's `TTL_LAMA_CONFIG_FILE` setting. It does not manage profile definitions,
85
+ `backend_config.yml`, or profile policies in the database. Replace masked
86
+ secrets with values or secret-file references before applying. Environment
87
+ variables continue to override YAML settings. Applying a file requires an
88
+ external server restart, and the CLI warns when the target is not covered by a
89
+ volume mount because the change may be lost when the container is replaced.
90
+
91
+ ```bash
92
+ ttlama global-config get --yaml
93
+ ttlama global-config diff --file config.yml --check-all
94
+ ttlama global-config validate --file config.yml
95
+ ttlama global-config apply --file config.yml --dry-run
96
+ ```
97
+
98
+ ## Installation and usage
99
+
100
+ The distribution is named `ttlama-cli` and installs the `ttlama` command. The instructions below install the current source checkout in editable mode and do not depend on PyPI. A new release will be published to PyPI in the future.
101
+
102
+ Requirements: Python 3.12 or later and an instance of TTL-LAMa accessible over HTTP(S). From the `cli/` directory, install the package in a virtual environment:
103
+
104
+ ```bash
105
+ python -m venv .venv
106
+ source .venv/bin/activate
107
+ python -m pip install -e .
108
+ ttlama --help
109
+ ```
110
+
111
+ Configure the instance. The URL includes the scheme and host; provide the port separately:
112
+
113
+ ```bash
114
+ ttlama config set-server http://localhost --port 8080
115
+ ```
116
+
117
+ Sign in with an internal account. The password is prompted for securely and is not passed as a command argument:
118
+
119
+ ```bash
120
+ ttlama auth login internal --user admin
121
+ ```
122
+
123
+ The command performs the CSRF exchange required by the API, then stores the access token returned by the server. It does not display the password or token.
124
+
125
+ Sign in with the configured OIDC provider. By default, the CLI opens a browser and listens for a short-lived callback on `127.0.0.1`; `--distant` instead displays a verification URL and user code for approval in another browser. The OIDC client secret stays on the server, and the CLI stores the Bearer token only after successful approval without displaying it.
126
+
127
+ ```bash
128
+ ttlama auth login oidc
129
+ ttlama auth login oidc --distant
130
+ ```
131
+
132
+ The distant flow requires the provider's discovery document to publish `device_authorization_endpoint` and support the `urn:ietf:params:oauth:grant-type:device_code` grant for the configured client.
133
+
134
+ Change the password of the signed-in account. The current password and the new password are prompted for securely, with a second prompt to confirm the new password. After success, all of the account's sessions are revoked, including the CLI token; sign in again to store a new token.
135
+
136
+ ```bash
137
+ ttlama auth password-chg
138
+ ```
139
+
140
+ Inspect the current session, including active session expirations, or close the session used by this CLI instance:
141
+
142
+ ```bash
143
+ ttlama auth status
144
+ ttlama auth status --json
145
+ ttlama auth status --yaml
146
+ ttlama auth status --check
147
+ ttlama auth logout
148
+ ```
149
+
150
+ `status` does not display access tokens or their hashes. With no locally stored token it reports a disconnected state and exits successfully; use `--check` to return a nonzero exit code instead. `logout` revokes only the current CLI session. It removes the local token after success, and also cleans up a token the server reports as invalid; a server/network error keeps the token so the operation can be retried. JSON and YAML status output contain `session` (`active` or `inactive`), `user` (`null` without a local token; otherwise `id`, `username`, `email`, and `is_admin`), and `sessions`, a list of `expires_at` timestamps.
151
+
152
+ ## Configuration and credentials
153
+
154
+ The instance address and port are stored in `config.json` under the user configuration directory determined by `platformdirs` (for example, the XDG directory on Linux). The URL must use `http` or `https` and must not contain credentials, query parameters, or a fragment.
155
+
156
+ The access token is stored in the system keyring through `keyring`, in one entry per configured instance. It is not written to the JSON configuration file. A password change revokes this token on the server; the next successful login replaces the local token.
157
+
158
+ ## Code layout
159
+
160
+ - `src/ttlama_cli/cli.py` defines the `ttlama` command and its groups.
161
+ - `src/ttlama_cli/commands/` contains the Typer commands, including `auth`, `config`, `global-config`, `admin`, `user`, and `backend`.
162
+ - `src/ttlama_cli/api_client.py` makes HTTP requests to the API.
163
+ - `src/ttlama_cli/config_store.py` validates and persists the configured instance.
164
+ - `src/ttlama_cli/token_store.py` encapsulates access to the system keyring.
165
+ - `tests/` contains the unit and integration tests.
166
+
167
+ ## Unit tests
168
+
169
+ Install the test dependencies, then run the test suite from `cli/`:
170
+
171
+ ```bash
172
+ python -m pip install -e '.[test]'
173
+ python -m pytest tests/
174
+ ```
175
+
176
+ ## Integration tests
177
+
178
+ The launcher starts an ephemeral instance from `ghcr.io/remiv1/ttl-lama:latest`, then runs authentication commands against the real server:
179
+
180
+ ```bash
181
+ ./scripts/test-integration.sh
182
+ ```
183
+
184
+ The launcher requires Podman Compose and access to the GHCR image. It checks that internal authentication succeeds and an incorrect password is rejected. The test server uses dedicated credentials, the keyring is replaced with in-memory storage, and no host volumes are mounted. The Compose project containers are stopped and removed when the script finishes.
185
+
186
+ ## Command tree
187
+
188
+ The current command groups are:
189
+
190
+ ```md
191
+ ttlama [--version]
192
+ ├── auth → **Authentication** → **_Who am I ?_**
193
+ │ ├── login
194
+ │ │ ├── internal --user <username>
195
+ │ │ └── oidc [--distant | none]
196
+ │ │
197
+ │ ├── logout
198
+ │ ├── password-chg
199
+ │ └── status [--json | --yaml | none] [--check | none]
200
+ │
201
+ ├── config
202
+ │ └── set-server <url> [--port <port>]
203
+ │
204
+ ├── user → **Utilization** → **_What am I using ?_**
205
+ │ ├── get
206
+ │ │
207
+ │ ├── devices
208
+ │ │ ├── ls
209
+ │ │ ├── get --id <device_id>
210
+ │ │ ├── add --file <file_path>
211
+ │ │ └── delete --id <device_id>
212
+ │ │
213
+ │ ├── leases
214
+ │ │ ├── ls
215
+ │ │ ├── get --id <lease_id>
216
+ │ │ ├── create --file <file_path>
217
+ │ │ └── revoke --id <lease_id>
218
+ │ │
219
+ │ └── profiles
220
+ │ ├── ls
221
+ │ └── get --id <profile_id>
222
+ │
223
+ ├── global-config → **Configuration** → **_How does the instance work ?_**
224
+ │ ├── get [--json | none] [--yaml | none]
225
+ │ ├── diff --file <file_path> [--check-all | none]
226
+ │ ├── validate --file <file_path>
227
+ │ └── apply --file <file_path> [--dry-run | none]
228
+ │
229
+ ├── admin → **Administration** → **_Who has what rights / What is the administered state ?_**
230
+ │ │
231
+ │ ├── users
232
+ │ │ ├── ls [--device <id> | none ] [--lease <id> | none ] [--profile <id> | none]
233
+ │ │ ├── get <user_id>
234
+ │ │ ├── create --file <file_path>
235
+ │ │ ├── update --user <user_id> --file <file_path>
236
+ │ │ ├── delete --user <user_id>
237
+ │ │ ├── assign --user <user_id> --profile <profile_id>
238
+ │ │ └── unassign --user <user_id> --profile <profile_id>
239
+ │ │
240
+ │ ├── devices
241
+ │ │ ├── ls [--lease <id> | none ] [--profile <id> | none]
242
+ │ │ ├── get --device <device_id>
243
+ │ │ ├── update --device <device_id> --file <file_path>
244
+ │ │ ├── block --device <device_id>
245
+ │ │ └── delete --device <device_id>
246
+ │ │
247
+ │ ├── leases
248
+ │ │ ├── ls [--user <id> | none ] [--device <id> | none ] [--profile <id> | none ] [--status <status> | none]
249
+ │ │ ├── get --lease <lease_id>
250
+ │ │ └── revoke --lease <lease_id>
251
+ │ │
252
+ │ └── profiles
253
+ │ ├── ls [--user <id>] [--device <id>] [--lease <id>]
254
+ │ ├── get --profile <profile_id> [--json | --yaml | none]
255
+ │ ├── create --file <file_path>
256
+ │ ├── update --profile <profile_id> --file <file_path>
257
+ │ └── delete --profile <profile_id>
258
+ │
259
+ └── backend → **Local VPN backend operations**
260
+ │
261
+ ├── wg
262
+ │ └── leases
263
+ │ ├── ls [--device <id> | none ]
264
+ │ ├── get --lease <lease_id>
265
+ │ ├── apply --file <file_path>
266
+ │ └── delete --lease <lease_id>
267
+ │
268
+ ├── openvpn
269
+ │ └── ...
270
+ │
271
+ └── ...
272
+ ```
273
+
274
+ The root command also supports `--install-completion` and `--show-completion`. Retrieve the complete CLI command documentation in [cli-reference.md](docs/cli-reference.md).
275
+
276
+ ### Input file examples
277
+
278
+ Ready-to-use JSON and YAML examples for every `--file` command are available in [docs/examples/](https://github.com/remiv1/TTL-LAMa-CLI/blob/main/docs/examples/): users (`users/user-create`, `users/user-update`), profiles (`profiles/profile-create`, `profiles/profile-update`), devices (`devices/device-add`, `devices/device-update`), and leases (`leases/lease-create`).
279
+
280
+ ### Admin user files
281
+
282
+ `ttlama admin users create --file` and `update --user <user_id> --file` accept UTF-8 JSON or YAML objects. Create files require `username`; `email`, `enabled`, `is_admin`, and `password` are optional. Update files contain only the fields to change; use `email: null` to clear the email address. A password in the input file is sent to the API but is never displayed by the CLI. If no password is supplied and the server uses internal authentication, the API generates one and the CLI displays it in the creation response only; save it immediately because it cannot be retrieved later. Without internal authentication, no internal credential is created when the password is omitted.
283
+
284
+ Create files may also include `oidc_links`, a list of identities identified by `issuer` and `subject`. Update files use `link_oidc` to add identities and `unlink_oidc` to remove them. Both values must exactly match the issuer and `sub` supplied by the OIDC provider; identities are not matched by email. An identity already linked to another account causes a conflict. Repeating a link or unlink operation has no additional effect. The CLI warns when unlinking because removing the last identity prevents future OIDC sign-in for that account.
285
+
286
+ The JSON or YAML output of `ttlama admin users get <user_id> --json` or `--yaml` is a flat object containing the editable fields returned by the API and can be passed directly to `update --user <user_id> --file`. List output remains a collection and is not an update body. Passwords are never returned; add a `password` field manually when changing one.
287
+
288
+ `ttlama admin users assign --user <user_id> --profile <profile_id>` assigns a
289
+ profile to a user; repeating the command is idempotent. The matching
290
+ `unassign` command revokes the active assignment and its associated leases.
291
+
292
+ ### Admin device files
293
+
294
+ `ttlama admin devices update --device <device_id> --file` accepts a UTF-8 JSON or YAML object with one or both of `name` and `public_key`. Device ownership and lifecycle fields cannot be changed. The JSON or YAML output of `ttlama admin devices get --device <device_id> --json` or `--yaml` contains only those editable fields and can be passed directly to `update --file`. The default console view shows the complete device record; the list table omits public keys, while structured list output contains the full API records. The `ls` filters `--lease` and `--profile` can be combined.
295
+
296
+ Both `block` and `delete` ask for confirmation and revoke the device's active leases. `block` marks the device as blocked; `delete` is a logical deletion that retains the device history.
297
+
298
+ ### Admin profile files
299
+
300
+ `ttlama admin profiles create --file` accepts a UTF-8 JSON or YAML object with `name`, `default_duration`, `maximum_duration`, and a non-empty `networks` list of CIDRs. Durations use `d`, `h`, `m`, or `s` units, and the default cannot exceed the maximum. For example:
301
+
302
+ ```yaml
303
+ name: office-access
304
+ default_duration: 1h
305
+ maximum_duration: 8h
306
+ networks:
307
+ - 10.0.0.0/24
308
+ ```
309
+
310
+ `update --profile <profile_id> --file` accepts any subset of those fields. `get --profile <profile_id> --json` and `--yaml` output a flat object that can be passed to `update --file`; `ls` filters `--user`, `--device`, and `--lease` are combined with AND. Historical profiles without a policy return only their name, so add the complete policy fields before updating one. Deleting a profile requires typing its full name, then revokes it and its dependent assignments and leases.