Skip to main content

TTL-LAMa CLI

English | Français

Python 3.12+ Typer License: Apache-2.0 Coverage

Logo

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.

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.

Project status

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).

Group Available commands Planned commands
config set-server —
auth login internal, login oidc, logout, password-chg, status —
user get, profiles ls, profiles get, devices ls/get/add/delete, leases ls/get/create/revoke —
global-config get, diff, validate, apply —
admin users ls, get, create, update, delete, assign, unassign —
admin devices ls, get, update, block, delete —
admin leases ls, get, revoke —
admin profiles ls, get, create, update, delete —
backend wg leases ls, get, apply, delete —
backend openvpn leases — ls, get, apply, delete

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 for exact arguments and input requirements.

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.

ttlama admin leases ls --status active --yaml
ttlama admin leases get --lease 73 --json
ttlama admin leases revoke --lease 73

Global configuration

ttlama global-config get reads the server's application YAML document; --json and --yaml emit the raw document structure. Direct secret values are shown as [REDACTED]. diff --file compares a local JSON or YAML candidate with the current file, compares redacted secrets on the server, and never prints direct secret values; --check-all also lists unchanged values. validate --file asks the server to validate a candidate without writing it. apply --file displays the changes and asks for confirmation; --dry-run validates and displays the diff without applying it.

This group writes only the application configuration file selected by the server's TTL_LAMA_CONFIG_FILE setting. It does not manage profile definitions, backend_config.yml, or profile policies in the database. Replace masked secrets with values or secret-file references before applying. Environment variables continue to override YAML settings. Applying a file requires an external server restart, and the CLI warns when the target is not covered by a volume mount because the change may be lost when the container is replaced.

ttlama global-config get --yaml
ttlama global-config diff --file config.yml --check-all
ttlama global-config validate --file config.yml
ttlama global-config apply --file config.yml --dry-run

Installation and usage

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.

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:

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
ttlama --help

Configure the instance. The URL includes the scheme and host; provide the port separately:

ttlama config set-server http://localhost --port 8080

Sign in with an internal account. The password is prompted for securely and is not passed as a command argument:

ttlama auth login internal --user admin

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.

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.

ttlama auth login oidc
ttlama auth login oidc --distant

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.

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.

ttlama auth password-chg

Inspect the current session, including active session expirations, or close the session used by this CLI instance:

ttlama auth status
ttlama auth status --json
ttlama auth status --yaml
ttlama auth status --check
ttlama auth logout

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.

Configuration and credentials

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.

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.

Code layout

  • src/ttlama_cli/cli.py defines the ttlama command and its groups.
  • src/ttlama_cli/commands/ contains the Typer commands, including auth, config, global-config, admin, user, and backend.
  • src/ttlama_cli/api_client.py makes HTTP requests to the API.
  • src/ttlama_cli/config_store.py validates and persists the configured instance.
  • src/ttlama_cli/token_store.py encapsulates access to the system keyring.
  • tests/ contains the unit and integration tests.

Unit tests

Install the test dependencies, then run the test suite from cli/:

python -m pip install -e '.[test]'
python -m pytest tests/

Integration tests

The launcher starts an ephemeral instance from ghcr.io/remiv1/ttl-lama:latest, then runs authentication commands against the real server:

./scripts/test-integration.sh

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.

Command tree

The current command groups are:

ttlama [--version]
 ├── auth → **Authentication** → **_Who am I ?_**
 │    ├── login
 │    │     ├── internal --user <username>
 │    │     └── oidc [--distant | none]
 │    │
 │    ├── logout
 │    ├── password-chg
 │    └── status [--json | --yaml | none] [--check | none]
 │
 ├── config
 │    └── set-server <url> [--port <port>]
 │
 ├── user → **Utilization** → **_What am I using ?_**
 │    ├── get
 │    │
 │    ├── devices
 │    │     ├── ls
 │    │     ├── get --id <device_id>
 │    │     ├── add --file <file_path>
 │    │     └── delete --id <device_id>
 │    │
 │    ├── leases
 │    │     ├── ls
 │    │     ├── get --id <lease_id>
 │    │     ├── create --file <file_path>
 │    │     └── revoke --id <lease_id>
 │    │
 │    └── profiles
 │          ├── ls
 │          └── get --id <profile_id>
 │
 ├── global-config → **Configuration** → **_How does the instance work ?_**
 │    ├── get [--json | none] [--yaml | none]
 │    ├── diff --file <file_path> [--check-all | none]
 │    ├── validate --file <file_path>
 │    └── apply --file <file_path> [--dry-run | none]
 │
 ├── admin → **Administration** → **_Who has what rights / What is the administered state ?_**
 │    │
 │    ├── users
 │    │     ├── ls [--device <id> | none ] [--lease <id> | none ] [--profile <id> | none]
 │    │     ├── get <user_id>
 │    │     ├── create --file <file_path>
 │    │     ├── update --user <user_id> --file <file_path>
 │    │     ├── delete --user <user_id>
 │    │     ├── assign --user <user_id> --profile <profile_id>
 │    │     └── unassign --user <user_id> --profile <profile_id>
 │    │
 │    ├── devices
 │    │     ├── ls [--lease <id> | none ] [--profile <id> | none]
 │    │     ├── get --device <device_id>
 │    │     ├── update --device <device_id> --file <file_path>
 │    │     ├── block --device <device_id>
 │    │     └── delete --device <device_id>
 │    │
 │    ├── leases
 │    │     ├── ls [--user <id> | none ] [--device <id> | none ] [--profile <id> | none ] [--status <status> | none]
 │    │     ├── get --lease <lease_id>
 │    │     └── revoke --lease <lease_id>
 │    │
 │    └── profiles
 │          ├── ls [--user <id>] [--device <id>] [--lease <id>]
 │          ├── get --profile <profile_id> [--json | --yaml | none]
 │          ├── create --file <file_path>
 │          ├── update --profile <profile_id> --file <file_path>
 │          └── delete --profile <profile_id>
 │
 └── backend → **Local VPN backend operations**
      │
      ├── wg
      │     └── leases
      │           ├── ls [--device <id> | none ]
      │           ├── get --lease <lease_id>
      │           ├── apply --file <file_path>
      │           └── delete --lease <lease_id>
      │
      ├── openvpn
      │     └── ...
      │
      └── ...

The root command also supports --install-completion and --show-completion. Retrieve the complete CLI command documentation in cli-reference.md.

Input file examples

Ready-to-use JSON and YAML examples for every --file command are available in 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).

Admin user files

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.

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.

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.

ttlama admin users assign --user <user_id> --profile <profile_id> assigns a profile to a user; repeating the command is idempotent. The matching unassign command revokes the active assignment and its associated leases.

Admin device files

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.

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.

Admin profile files

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:

name: office-access
default_duration: 1h
maximum_duration: 8h
networks:
      - 10.0.0.0/24

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.

Metadata

Release files for ttlama-cli 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ttlama-cli 0.1.0
File Size Uploaded Provenance Actions
ttlama_cli-0.1.0.tar.gz 59.8 kB Without provenance Details for ttlama_cli-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ttlama-cli 0.1.0
File Interpreter ABI Platform Actions
ttlama_cli-0.1.0-py3-none-any.whl Python 3 none any Details for ttlama_cli-0.1.0-py3-none-any.whl

Total release size: 114.4 kB

Release files / ttlama_cli-0.1.0.tar.gz

Download URL ttlama_cli-0.1.0.tar.gz
Size 59.8 kB
Tags Source
SHA-256 checksum
How to use checksums
fccd8c8c6ad2fc12b510e9bdbb9042cf1c2cffb44b966ff0e49ef1e4de897394
BLAKE2b-256 checksum
How to use checksums
a6117e19d11aa0af938df478d9aeb1d1715cb1ec202f5352f20acacdb1b2db73
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Release files / ttlama_cli-0.1.0-py3-none-any.whl

Download URL ttlama_cli-0.1.0-py3-none-any.whl
Size 54.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d9efe1e59e5dbbbcf3a4f433da3f0719f7a97089c70c0c3029d33ead61bd107e
BLAKE2b-256 checksum
How to use checksums
1114a10725b59d6ebb10c03f32f1fc904e90878afe31d8cc7140117e2f42b7ae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Security for ttlama-cli 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page