fnox-py

fnox-py is a thin Python wrapper around the fnox secrets management tool.

It does not reimplement fnox behavior in Python. Instead, it:

locates a real fnox binary
builds argv for common commands
runs the binary
returns parsed results or typed errors

Python requirement: >=3.12

[!NOTE] Official fnox project links:

GitHub repo: jdx/fnox

Fnox docs: https://fnox.jdx.dev

Installation

uv

uv tool install fnox-py

pip

pip install fnox-py

Bundled binary vs source install

Platform wheels are intended to bundle the fnox binary.

If you install from source instead of a platform wheel, fnox-py requires a real fnox executable to be available via:

PATH, or
FNOX_PY_BINARY=/absolute/path/to/fnox

Examples:

pip install --no-binary fnox-py fnox-py

FNOX_PY_BINARY=/usr/local/bin/fnox python -c "import fnox_py; print(fnox_py.version())"

Binary Resolution

At runtime, fnox-py resolves the fnox binary in this order:

FNOX_PY_BINARY
bundled/installed locations in the current environment
bundled/installed fallback locations associated with the base or target install
user scheme script location
PATH

If FNOX_PY_BINARY is set but points to a missing file, fnox-py raises FnoxNotFoundError.

Python API

from fnox_py import (
    config_files,
    export_json,
    get,
    lease_create,
    profiles,
    providers,
    schema,
    version,
)

value = get("MY_SECRET")
all_values = export_json()
schema_doc = schema()
profile_names = profiles()
provider_names = providers()
config_paths = config_files()
lease = lease_create("vault", duration="1h", label="local-dev")
fnox_version = version()

Common examples

Get a single value:

from fnox_py import get

token = get("API_TOKEN")

Get a value from a specific profile:

from fnox_py import get

token = get("API_TOKEN", profile="prod")

Decode base64 output:

from fnox_py import get

decoded = get("TLS_CERT", base64_decode=True)

Export all secrets as JSON:

from fnox_py import export_json

data = export_json(profile="dev")

Inspect schema, profiles, providers, and config files:

from fnox_py import config_files, profiles, providers, schema

print(schema())
print(profiles())
print(providers())
print(config_files())

Create a lease:

from fnox_py import lease_create

lease = lease_create("vault", duration="30m", label="ci-job")

Get the underlying fnox version:

from fnox_py import version

print(version())

CLI

The package installs the fnox-py console script.

Built-in subcommands

Locate the resolved binary:

fnox-py which

Show the wrapper version and attempt to print the underlying fnox version:

fnox-py version

Print basic environment diagnostics:

fnox-py doctor

Passthrough behavior

Any arguments other than which, version, and doctor are passed directly through to fnox.

For example:

fnox-py get MY_SECRET
fnox-py profiles
fnox-py export --format json

With no arguments, fnox-py runs fnox with no extra argv.

Public API

fnox-py currently exports:

config_files
export_json
get
lease_create
profiles
providers
schema
version
find_fnox_bin
run
FnoxResult
FnoxCommandError
FnoxError
FnoxNotFoundError
FnoxTimeoutError

Errors

Library calls raise typed exceptions:

FnoxNotFoundError when the binary cannot be found
FnoxCommandError when fnox exits non-zero
FnoxTimeoutError on subprocess timeout
FnoxError as the base exception type

Development

This project uses uv, pytest, ruff, and mypy.

Install dependencies:

uv sync

Run tests:

uv run pytest -v

Run a single test:

uv run pytest tests/test_api.py::test_get -q

Lint:

uv run ruff check src tests scripts

Type-check:

uv run mypy src

Build distributions:

uv build

Release / Platform Wheel Build

scripts/build_platform_wheel.py builds platform-specific wheels by:

building a pure Python wheel
downloading upstream fnox release binaries
injecting the binary into the wheel
rewriting wheel metadata
building an sdist

The upstream fnox version to bundle is read from FNOX_VERSION.txt at the repo root by default. To override it, pass --fnox-version:

uv run python scripts/build_platform_wheel.py --fnox-version 1.0.0 --output dist/

Expected upstream archive and extracted binary SHA256 values are pinned in FNOX_HASHES.json and verified during release builds.

To bump the bundled version, update FNOX_VERSION.txt, refresh FNOX_HASHES.json, and commit both changes.

Notes

fnox-py is intentionally small and wrapper-focused.
For behavior, flags, and command semantics, prefer the upstream fnox documentation.
If you need lower-level control, use run() directly and inspect FnoxResult.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

fnox_py-1.31.0.tar.gz (6.6 kB view details)

Uploaded Jul 18, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

fnox_py-1.31.0-py3-none-win_arm64.whl (15.6 MB view details)

Uploaded Jul 18, 2026 Python 3Windows ARM64

fnox_py-1.31.0-py3-none-win_amd64.whl (16.7 MB view details)

Uploaded Jul 18, 2026 Python 3Windows x86-64

fnox_py-1.31.0-py3-none-manylinux_2_17_x86_64.whl (24.6 MB view details)

Uploaded Jul 18, 2026 Python 3manylinux: glibc 2.17+ x86-64

fnox_py-1.31.0-py3-none-manylinux_2_17_aarch64.whl (23.8 MB view details)

Uploaded Jul 18, 2026 Python 3manylinux: glibc 2.17+ ARM64

fnox_py-1.31.0-py3-none-macosx_11_0_arm64.whl (18.1 MB view details)

Uploaded Jul 18, 2026 Python 3macOS 11.0+ ARM64

fnox_py-1.31.0-py3-none-macosx_10_12_x86_64.whl (19.7 MB view details)

Uploaded Jul 18, 2026 Python 3macOS 10.12+ x86-64

File details

Details for the file fnox_py-1.31.0.tar.gz.

File metadata

Download URL: fnox_py-1.31.0.tar.gz
Upload date: Jul 18, 2026
Size: 6.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for fnox_py-1.31.0.tar.gz
Algorithm	Hash digest
SHA256	`ef26fc01240a3d48a42bd7ff2ca8983383a54b78963e01e1cd2a8496546b7560`
MD5	`062ead10df6f433ab3204b107f530073`
BLAKE2b-256	`c66ade5b9ba7bef3bb3b0c94100c4d177668acfed988aba8425b3affe5f95271`

See more details on using hashes here.

Provenance

The following attestation bundles were made for fnox_py-1.31.0.tar.gz:

Publisher: release.yml on fullerzz/fnox-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: fnox_py-1.31.0.tar.gz
- Subject digest: ef26fc01240a3d48a42bd7ff2ca8983383a54b78963e01e1cd2a8496546b7560
- Sigstore transparency entry: 2193303929
- Sigstore integration time: Jul 18, 2026
Source repository:
- Permalink: fullerzz/fnox-py@04c4446d8dae2d2d93824f4d8b1c952f29741cdc
- Branch / Tag: refs/tags/v1.31.0
- Owner: https://github.com/fullerzz
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@04c4446d8dae2d2d93824f4d8b1c952f29741cdc
- Trigger Event: workflow_dispatch

File details

Details for the file fnox_py-1.31.0-py3-none-win_arm64.whl.

File metadata

Download URL: fnox_py-1.31.0-py3-none-win_arm64.whl
Upload date: Jul 18, 2026
Size: 15.6 MB
Tags: Python 3, Windows ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for fnox_py-1.31.0-py3-none-win_arm64.whl
Algorithm	Hash digest
SHA256	`74d5deb7d48cbfb6e5c553116aba0eaceafffc92490dd07e78059effa21fd76a`
MD5	`d2030541f537bfaa0b67fed81ed15f18`
BLAKE2b-256	`860f9e6f2049b3fb3913ef8d2afc8246b6b0c5428f2a87fc9b6acc93ff7baba5`

See more details on using hashes here.

Provenance

The following attestation bundles were made for fnox_py-1.31.0-py3-none-win_arm64.whl:

Publisher: release.yml on fullerzz/fnox-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: fnox_py-1.31.0-py3-none-win_arm64.whl
- Subject digest: 74d5deb7d48cbfb6e5c553116aba0eaceafffc92490dd07e78059effa21fd76a
- Sigstore transparency entry: 2193303936
- Sigstore integration time: Jul 18, 2026
Source repository:
- Permalink: fullerzz/fnox-py@04c4446d8dae2d2d93824f4d8b1c952f29741cdc
- Branch / Tag: refs/tags/v1.31.0
- Owner: https://github.com/fullerzz
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@04c4446d8dae2d2d93824f4d8b1c952f29741cdc
- Trigger Event: workflow_dispatch

File details

Details for the file fnox_py-1.31.0-py3-none-win_amd64.whl.

File metadata

Download URL: fnox_py-1.31.0-py3-none-win_amd64.whl
Upload date: Jul 18, 2026
Size: 16.7 MB
Tags: Python 3, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for fnox_py-1.31.0-py3-none-win_amd64.whl
Algorithm	Hash digest
SHA256	`f48b7166ddaacf3f5639931d0cd1c7b830d54daa84f544784a7230091ee829a1`
MD5	`09fd250878616bd0f1a6f140192d6df4`
BLAKE2b-256	`2fee821978442e207240f51781b52bc1c079d4274609451bec08742e749eecdd`

See more details on using hashes here.

Provenance

The following attestation bundles were made for fnox_py-1.31.0-py3-none-win_amd64.whl:

Publisher: release.yml on fullerzz/fnox-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: fnox_py-1.31.0-py3-none-win_amd64.whl
- Subject digest: f48b7166ddaacf3f5639931d0cd1c7b830d54daa84f544784a7230091ee829a1
- Sigstore transparency entry: 2193303948
- Sigstore integration time: Jul 18, 2026
Source repository:
- Permalink: fullerzz/fnox-py@04c4446d8dae2d2d93824f4d8b1c952f29741cdc
- Branch / Tag: refs/tags/v1.31.0
- Owner: https://github.com/fullerzz
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@04c4446d8dae2d2d93824f4d8b1c952f29741cdc
- Trigger Event: workflow_dispatch

File details

Details for the file fnox_py-1.31.0-py3-none-manylinux_2_17_x86_64.whl.

File metadata

Download URL: fnox_py-1.31.0-py3-none-manylinux_2_17_x86_64.whl
Upload date: Jul 18, 2026
Size: 24.6 MB
Tags: Python 3, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for fnox_py-1.31.0-py3-none-manylinux_2_17_x86_64.whl
Algorithm	Hash digest
SHA256	`8e8239a8a357fb55010902bb81d066de3b4a9c954eaa65d502df15d189f1eba3`
MD5	`9cf1276bf16731d987ed296c27dadaac`
BLAKE2b-256	`68d768d0e5d5473deca17df3b032805aa37c433d2683fcaef25ce0d1548927cf`

See more details on using hashes here.

Provenance

The following attestation bundles were made for fnox_py-1.31.0-py3-none-manylinux_2_17_x86_64.whl:

Publisher: release.yml on fullerzz/fnox-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: fnox_py-1.31.0-py3-none-manylinux_2_17_x86_64.whl
- Subject digest: 8e8239a8a357fb55010902bb81d066de3b4a9c954eaa65d502df15d189f1eba3
- Sigstore transparency entry: 2193303953
- Sigstore integration time: Jul 18, 2026
Source repository:
- Permalink: fullerzz/fnox-py@04c4446d8dae2d2d93824f4d8b1c952f29741cdc
- Branch / Tag: refs/tags/v1.31.0
- Owner: https://github.com/fullerzz
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@04c4446d8dae2d2d93824f4d8b1c952f29741cdc
- Trigger Event: workflow_dispatch

File details

Details for the file fnox_py-1.31.0-py3-none-manylinux_2_17_aarch64.whl.

File metadata

Download URL: fnox_py-1.31.0-py3-none-manylinux_2_17_aarch64.whl
Upload date: Jul 18, 2026
Size: 23.8 MB
Tags: Python 3, manylinux: glibc 2.17+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for fnox_py-1.31.0-py3-none-manylinux_2_17_aarch64.whl
Algorithm	Hash digest
SHA256	`4081aa8766b02939b1312820519b969e6634ee38799c2f38229e9ee764deaf54`
MD5	`9a1af238d11852e86705a537bdb4c5c1`
BLAKE2b-256	`0bd71051b08f575c7d28e3eb70122054d576d8f52a5aff3771478e6e2fe41972`

See more details on using hashes here.

Provenance

The following attestation bundles were made for fnox_py-1.31.0-py3-none-manylinux_2_17_aarch64.whl:

Publisher: release.yml on fullerzz/fnox-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: fnox_py-1.31.0-py3-none-manylinux_2_17_aarch64.whl
- Subject digest: 4081aa8766b02939b1312820519b969e6634ee38799c2f38229e9ee764deaf54
- Sigstore transparency entry: 2193303966
- Sigstore integration time: Jul 18, 2026
Source repository:
- Permalink: fullerzz/fnox-py@04c4446d8dae2d2d93824f4d8b1c952f29741cdc
- Branch / Tag: refs/tags/v1.31.0
- Owner: https://github.com/fullerzz
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@04c4446d8dae2d2d93824f4d8b1c952f29741cdc
- Trigger Event: workflow_dispatch

File details

Details for the file fnox_py-1.31.0-py3-none-macosx_11_0_arm64.whl.

File metadata

Download URL: fnox_py-1.31.0-py3-none-macosx_11_0_arm64.whl
Upload date: Jul 18, 2026
Size: 18.1 MB
Tags: Python 3, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for fnox_py-1.31.0-py3-none-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`a5fb358c576d32e3bfbc919bc7392bb2c5fdf568dea6237ae45872c6675aad5f`
MD5	`17a35cca39e4321dac86ace690625064`
BLAKE2b-256	`2613471196840eec8db7220b5fa96e61d3e446b98dfe09a102287d975876d97b`

See more details on using hashes here.

Provenance

The following attestation bundles were made for fnox_py-1.31.0-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on fullerzz/fnox-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: fnox_py-1.31.0-py3-none-macosx_11_0_arm64.whl
- Subject digest: a5fb358c576d32e3bfbc919bc7392bb2c5fdf568dea6237ae45872c6675aad5f
- Sigstore transparency entry: 2193303970
- Sigstore integration time: Jul 18, 2026
Source repository:
- Permalink: fullerzz/fnox-py@04c4446d8dae2d2d93824f4d8b1c952f29741cdc
- Branch / Tag: refs/tags/v1.31.0
- Owner: https://github.com/fullerzz
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@04c4446d8dae2d2d93824f4d8b1c952f29741cdc
- Trigger Event: workflow_dispatch

File details

Details for the file fnox_py-1.31.0-py3-none-macosx_10_12_x86_64.whl.

File metadata

Download URL: fnox_py-1.31.0-py3-none-macosx_10_12_x86_64.whl
Upload date: Jul 18, 2026
Size: 19.7 MB
Tags: Python 3, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for fnox_py-1.31.0-py3-none-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`e9627d63fdfcc7e66a8425f130b37b9afed07b89a14476f0f60eb188b3b3965a`
MD5	`2852699550de87d98fc560e04fb2ace6`
BLAKE2b-256	`2debd19b931569757d9c6791a87ce4d9882521e1e2de637162e53df381def9ca`

See more details on using hashes here.

Provenance

The following attestation bundles were made for fnox_py-1.31.0-py3-none-macosx_10_12_x86_64.whl:

Publisher: release.yml on fullerzz/fnox-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: fnox_py-1.31.0-py3-none-macosx_10_12_x86_64.whl
- Subject digest: e9627d63fdfcc7e66a8425f130b37b9afed07b89a14476f0f60eb188b3b3965a
- Sigstore transparency entry: 2193303961
- Sigstore integration time: Jul 18, 2026
Source repository:
- Permalink: fullerzz/fnox-py@04c4446d8dae2d2d93824f4d8b1c952f29741cdc
- Branch / Tag: refs/tags/v1.31.0
- Owner: https://github.com/fullerzz
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@04c4446d8dae2d2d93824f4d8b1c952f29741cdc
- Trigger Event: workflow_dispatch