Metadata-Version: 2.4
Name: ophix-conf-client
Version: 2026.10.6.1
Summary: Configuration client for Ophix Project Servers
Author: Ophix Project
License-Expression: MIT
Project-URL: Homepage, https://ophix.io
Project-URL: Documentation, https://github.com/ophixproject/ophix-conf-client#readme
Project-URL: Source, https://github.com/ophixproject/ophix-conf-client
Keywords: ophix,fleet management,configuration,client
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ophix-client-core>=2026.06.16.02
Requires-Dist: requests>=2.28
Requires-Dist: python-dotenv>=1.0
Requires-Dist: distro>=1.8
Requires-Dist: urllib3>=1.26
Dynamic: license-file

# ophix-conf-client

Python client for [ophix-confs](https://github.com/ophixproject/ophix-confs) configuration servers.

Provides a CLI for operators and an importable library for automation scripts
and Tier 2 clients. Fetches named configuration snippets (YAML, JSON, XML, INI,
TOML, .env, raw) verbatim from the server.

---

## Installation

```bash
pip install ophix-conf-client venv-cmds
```

`venv-cmds` is optional but recommended — it provides `venv-cmds list` to discover all
commands available in the venv and `venv-cmds check_updates` to check for new releases.

---

## Quick start

```bash
# Bootstrap in one step
conf-client quickstart https://confserver.internal my-client

# Fetch a configuration (raw content printed to stdout)
conf-client fetch nginx_upstream

# Fetch with format info header
conf-client fetch nginx_upstream --format-info

# Import a configuration file
conf-client import --input-file nginx.conf --name nginx_upstream --format raw

# Import with format inferred from extension
conf-client import --input-file app_config.yaml --name app_config

# Check all configurations mapped in .conf.env
conf-client check --all

# Diagnose config and connectivity
conf-client doctor
```

---

## Configuration

Settings are stored in `.conf.env` (mode 600).

| Variable | Purpose |
| --- | --- |
| `CONFSERVER_URL` | Base URL of the configuration server |
| `CONFSERVER_API_TOKEN` | 64-char hex API token (set by `register`) |
| `CONFSERVER_CA_CERT` | Path to CA certificate (set by `download ca-cert`) |

Additional keys in `.conf.env` are treated as configuration name mappings used by
`check --all` — each key maps an environment variable name to a configuration name
on the server.

---

## CLI reference

```text
conf-client quickstart <server_url> <client_name> [--deployment-ref ...]
conf-client fetch {--name <n>|--var <VAR>} [--output-file <path>] [--format-info]
conf-client register <name> [deployment_ref]
conf-client update [--deployment-ref ...]
conf-client set {server|ca-cert|token} <value>
conf-client download ca-cert
conf-client import --input-file <file> [--name <n>] [--var <VAR>] [--format <fmt>] [--overwrite]
conf-client check {--all|--var <VAR>|--name <name>} [--verbose]
conf-client info
conf-client rotate-token
conf-client doctor
```

### fetch

| Usage | What happens |
| --- | --- |
| `--name <n>` | Fetches the configuration named `<n>` directly |
| `--var <VAR>` | Reads the configuration name from `<VAR>` in `.conf.env`, then fetches it |

`--output-file <path>` writes the content directly to a file instead of stdout. Parent directories are created automatically. Use `-` as the path for explicit stdout. When writing to a file, `--format-info` prints format and timestamp to stdout separately rather than embedding them in the file.

### import

| Usage | What happens |
| --- | --- |
| `--name <n>` only | Imports configuration named `<n>`. No `.conf.env` changes. |
| `--var <VAR>` only | Reads the configuration name from `<VAR>` in `.conf.env`. Fails if not set. |
| `--name <n> --var <VAR>` | Imports `<n>` and writes `<VAR>=<n>` to `.conf.env`. Fails if `<VAR>` is already mapped to a different name. |

Add `--overwrite` to update an existing configuration.

---

## Python API — Tier 2 clients

```python
from conf_client.core import get_config

# Reads config name from the named env var, fetches from server,
# returns raw content string. Calls sys.exit(1) on failure.
nginx_conf = get_config("NGINX_CONFIG_NAME")

# Write directly to file
with open("/etc/nginx/conf.d/upstream.conf", "w") as f:
    f.write(nginx_conf)
```

Full CRUD:

```python
from conf_client.core import (
    fetch_config,    # returns (content, format_name, updated_at)
    create_config,
    update_config,
    delete_config,
)
```

`fetch_config` returns a `(content, format_name, updated_at)` tuple rather than a dict,
since the content is raw text. The format name and timestamp come from response headers.
`get_config` returns the raw content string directly.

---

## Server

This client connects to [ophix-confs](https://github.com/ophixproject/ophix-confs).
