signpdf-ui
An interactive terminal UI (TUI) that wraps pyhanko so you can sign PDFs on Linux without memorizing flags.
Advantages over Okular (which can also sign PDFs):
- Easier setup (e.g. no Thunderbird needed)
- Better customization of visual representation (text and watermark image)
Install
pip install signpdf-ui
After installing, run the one-time setup once:
signpdf-ui --init
This copies the bundled configuration templates (signpdf-ui.yml, pyhanko.yml, watermark.png) into your user config directory — typically ~/.config/signpdf-ui/ on Linux. Use --init --force to overwrite existing files.
Getting started
Run
signpdf-ui --demo
to copy bundled demo PDFs to /tmp/pdfsign-ui-demo-<timestamp>/ and print usage instructions.
You can play around with those files and the bundled p12-certificate (password: KXzolC-test-pw-s9Ckp7oZ) — created for this demonstration purpose only.
Customization
To make signpdf-ui actually useful you have to customize it:
-
signpdf-ui→ button "Edit config for user interface" → insert the path for your p12 certificate atdefault_cert: ....
-
signpdf-ui→ button "Edit config for backend (pyhanko)" → adapt the stamp text to your needs.
-
- (optional) Adapt the png watermark image at
$HOME/.config/signpdf-ui/watermark.pngor set a different one. This has great impact on the visual appearance of your signature.
- (optional) Adapt the png watermark image at
Test your setup with the demo PDF-files.
Usage
Interactive UI
Three ways to launch the wizard:
| Command | When to use |
|---|---|
signpdf-ui |
Files are in the working directory — pick them inside the wizard. |
signpdf-ui FILE.pdf |
You already know the file — opens directly at step 2 (mode selection). |
signpdf-ui "docs/*.pdf" |
Multiple files matching a glob — opens at step 2 with all matches pre-loaded. |
When started with a file or pattern, press Alt+← at any point to go back to step 1 (file path pre-filled).
Main menu entries:
- Sign PDF(s) — four-step wizard: file/pattern → mode (existing signature field or custom area) → field/rect → certificate → confirm & sign. The confirmation screen shows the exact
pyhanko sign addsig ...command(s) inline, with a Copy to clipboard button. - Edit config for user interface / Edit config for backend (pyhanko) — opens the respective YAML file in
$VISUAL/$EDITOR(orxdg-open). - Send feedback — opens a dialog to send a short message (and optional e-mail address) to the developer.
- Quit (Ctrl+q) — exits (also available from any screen).
Defining the signature area visually with Okular
When you choose "Place the signature in a custom area", the UI automatically extracts any existing rect annotations from the file and lists them for you to pick. If none are present (or you want a new one):
- Click "Open copy in Okular to draw rect". A temporary copy of the PDF opens in Okular — the original file is never touched.
- In Okular, select the Rectangle annotation tool (1. Activate annotation toolbar from Tools menu or press (F6); 2. Select Rectangle (hidden inside the Arrow-dropdown) or press Alt + 0).
- Draw a rectangle over the desired signature area, save with Ctrl+S, then close Okular. The UI reads the temp file automatically and imports the new rectangle.
- Adjust the page number (before the
/character) if needed, then proceed.
Note: Save with Ctrl+S in Okular (not the sidecar
.okularformat). Draw exactly one rectangle — the UI will complain otherwise.
Non-interactive CLI
For (batch) signing without the UI, use pyhanko sign addsig directly — the confirmation screen in the UI shows the exact invocation, which you can copy to the clipboard as a starting point.
Configuration
signpdf-ui.yml lives next to pyhanko.yml in the user config dir. Keys:
| Key | Purpose |
|---|---|
default_cert |
Path to a .p12 file used as the default in the cert picker. |
pyhanko_config |
Path to the pyhanko style YAML. Relative paths resolve against the directory of signpdf-ui.yml. |
style_name |
Stamp style name (must exist in pyhanko.yml). |
editor |
Optional editor command override for the "Edit config" buttons. |
The bundled pyhanko.yml defines a single stamp style my-signature with a watermark background. To change name, layout, watermark, etc., edit pyhanko.yml directly (see pyhanko's stamp documentation).
Development
pip install -e .
python -m pytest
Test layout:
tests/test_core.py— unit tests for command building and the two parsers (field-list parser, rect extractor). These are the things most likely to break under future pyhanko or PDF format changes, so they get explicit coverage.tests/test_e2e.py— invokes the realpyhanko sign addsigagainst the bundled demo PDFs and the test certificate. Skipped ifpyhankois not onPATH.tests/test_tui.py— headless Textual pilot tests for visual layout and wizard navigation (usesIsolatedAsyncioTestCase+ Textual'srun_test).tests/fixtures/— demo PDFs + a self-signed test certificate (passwordKXzolC-test-pw-s9Ckp7oZ, not used anywhere else).
Metadata
Release files for signpdf-ui 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| signpdf_ui-0.2.0.tar.gz | 174.4 kB | Without provenance | Details for signpdf_ui-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| signpdf_ui-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for signpdf_ui-0.2.0-py3-none-any.whl |
Total release size: 275.6 kB
Release files / signpdf_ui-0.2.0.tar.gz
| Download URL | signpdf_ui-0.2.0.tar.gz |
|---|---|
| Size | 174.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ea375cae1e7c296043cf2f742172f441a0c55755114b9dcfed15103ebe89899a
|
|
BLAKE2b-256 checksum How to use checksums |
0c8920a4e151fe485d513372c98fbd419778e5c0666d530547bd0f6d82cc386f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.4
|
Release files / signpdf_ui-0.2.0-py3-none-any.whl
| Download URL | signpdf_ui-0.2.0-py3-none-any.whl |
|---|---|
| Size | 101.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3599342db055082c5f78674c758b5329aecb09137512b6996fd0b59d4201020c
|
|
BLAKE2b-256 checksum How to use checksums |
196d639c26be91b17e10941c140d513b6b04296fbf54a0e7f07e79ea8352f379
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.4
|
Security for signpdf-ui 0.2.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.