Metadata-Version: 2.4
Name: pesign-cli
Version: 0.1.0
Summary: Command-line client for the PESIGN PDF signing API
Author: Christ ND
License: Proprietary
Keywords: pdf,signature,pades,globalsign-dss,cli,HSM
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-dotenv>=1.0.0

# PESIGN CLI

Command-line client for the PESIGN PDF signing API.

PESIGN allows users to securely sign PDF documents through a hosted PESIGN API. The CLI is installed locally and communicates with the remote API over HTTPS.

The GlobalSign DSS credentials and mTLS certificate/key stay on the server. Users only need PESIGN-generated API keys and secrets.



## Features

* Check PESIGN API health
* Sign PDF files
* Create user signing API keys
* List signing API keys
* Revoke signing API keys
* Create admin keys
* List admin keys
* Revoke admin keys
* Admin-only user creation
* Admin-only user listing
* Admin-only user deletion



## Requirements

* Python 3.11 or newer
* Access to a running PESIGN API server
* Valid PESIGN user credentials or API credentials



## Installation

### Install from package

```bash
pip install pesign-cli
```

### Install locally for development

From inside the `pesign-cli` folder:

```bash
pip install -e .
```

After installation, confirm the CLI is available:

```bash
pesign --help
```



## Configuration

Create a `.env` file in the folder where you run the CLI.

Example:

```env
PESIGN_API_URL=https://pesign.christnd.codes
```

You can also pass the API URL directly with:

```bash
--api-url https://pesign.christnd.codes
```

## Authentication

PESIGN uses different credentials depending on the action.

### Signing API credentials

Used for signing PDFs:

```text
pe_ak_...
pe_sk_...
```

The API key is passed as an option. The secret is prompted securely.

### User password

Used for:

* Creating API keys
* Listing API keys
* Revoking API keys
* Creating admin keys
* Listing admin keys
* Revoking admin keys

The password is prompted securely.

### Admin key credentials

Used for admin actions:

```text
pe_admin_ak_...
pe_admin_sk_...
```

Admin keys are required for:

* Creating users
* Listing users
* Deleting users

The admin key is passed as an option. The admin secret is prompted securely.

## Commands

### Health check

```bash
pesign health
```

With explicit API URL:

```bash
pesign health --api-url https://pesign.christnd.codes
```

## Sign a PDF

```bash
pesign sign input.pdf signed.pdf \
  --api-key "YOUR_API_KEY" \
  --reason "Approved contract" \
  --location "Paris, FR" \
  --name "C.ND" \
  --overwrite
```

The CLI will prompt for:

```text
API Secret:
```

### Windows PowerShell example

```powershell
pesign sign .\input.pdf .\signed.pdf `
  --api-key "YOUR_API_KEY" `
  --reason "Approved contract" `
  --location "Paris, FR" `
  --name "C.ND" `
  --overwrite
```


## Create a signing API key

```bash
pesign create-api-key \
  --user username \
  --name "Test signing key"
```

The CLI will prompt for the user's password. The API secret is shown only once. Store it securely.

## List signing API keys

```bash
pesign list-api-keys --user username
```

The CLI will prompt for the user's password. The output includes copyable API key IDs. Use the ID when revoking a key.

## Revoke a signing API key

```bash
pesign revoke-api-key \
  --user username \
  --id "API_KEY_ID"
```

Example:

```bash
pesign revoke-api-key \
  --user username \
  --id "f63da227-8c29-44a8-a81f-2127190c6f5c"
```

The CLI will prompt for the user's password.

## Create an admin key

```bash
pesign create-admin-key \
  --user username \
  --name "ND temporary admin key"
```

The CLI will prompt for the admin user's password. Admin keys are short-lived and should be stored securely.

## List admin keys

```bash
pesign list-admin-keys --user username
```

The CLI will prompt for the admin user's password. The output includes copyable admin key IDs. Use the ID when revoking an admin key.

## Revoke an admin key

```bash
pesign revoke-admin-key \
  --user username \
  --id "ADMIN_KEY_ID"
```

Example:

```bash
pesign revoke-admin-key \
  --user username \
  --id "eb6ccb9c-bc7b-443f-b95d-c4a42f254e71"
```

The CLI will prompt for the admin user's password.

## Create a user

Requires an active admin key.

```bash
pesign create-user john \
  --role signer \
  --api-key-name "John first signing key" \
  --admin-key "pe_admin_ak_YOUR_ADMIN_KEY"
```

The CLI will prompt for:

```text
Admin Secret:
Password:
Confirm password:
```

Allowed roles are usually:

```text
admin
signer
viewer
```

The created user's first API secret is shown only once. Store it securely.

## List users

Requires an active admin key.

```bash
pesign list-users \
  --admin-key "YOUR_ADMIN_KEY"
```

The CLI will prompt for:

```text
Admin Secret:
```

## Delete a user

Requires an active admin key.

```bash
pesign delete-user john \
  --admin-key "YOUR_ADMIN_KEY"
```

The CLI will prompt for:

```text
Admin Secret:
```

## Common Options

Most commands support:

```bash
--api-url
```

Example:

```bash
pesign health --api-url https://pesign.christnd.codes
```

Some commands also support timeout options depending on the installed CLI version:

```bash
--timeout 60
```

## Environment Variables

| Variable                         |    Required | Description                     |
| -------------------------------- | ----------: | ------------------------------- |
| `PESIGN_API_URL`                 | Recommended | Default PESIGN API URL          |
| `PESIGN_CF_ACCESS_CLIENT_ID`     |    Optional | Cloudflare Access client ID     |
| `PESIGN_CF_ACCESS_CLIENT_SECRET` |    Optional | Cloudflare Access client secret |

Example `.env`:

```env
PESIGN_API_URL=https://pesign.christnd.codes
```


## Troubleshooting

### `pesign` command not found

Make sure the package is installed in the active Python environment:

```bash
pip show pesign-cli
```

On Windows:

```powershell
where pesign
```

Inside a virtual environment, the command should usually point to:

```text
.venv\Scripts\pesign.exe
```

### API not reachable

Check:

```bash
pesign health --api-url https://pesign.christnd.codes
```

Also confirm the server health endpoint works:

```bash
curl https://pesign.christnd.codes/v1/health
```

### Invalid API credentials

Confirm that you are using:

```text
X-PESIGN-API-Key     -> pe_ak_...
X-PESIGN-API-Secret  -> pe_sk_...
```

For signing, do not use admin keys.

### Invalid admin credentials

Confirm that you are using:

```text
X-PESIGN-Admin-Key     -> pe_admin_ak_...
X-PESIGN-Admin-Secret  -> pe_admin_sk_...
```

Admin keys may expire and may need to be regenerated.


## Development

Install in editable mode:

```bash
pip install -e .
```

Run:

```bash
pesign --help
```

Build package:

```bash
python -m build
```

Check package:

```bash
twine check dist/*
```

Install built wheel:

```bash
pip install dist/pesign_cli-0.1.0-py3-none-any.whl
```


## License

Proprietary.

All rights reserved.
