CLI Reference
CLI Reference
Global flags
These flags apply to all commands:
| Flag | Short | Default | Description |
|---|---|---|---|
--path <dir> | ~/.upki/ca | Data directory (overridden by UPKI_DATA_DIR) |
Commands
init
Initialise the CA. On the first run, creates the root key pair, self-signed certificate, and default configuration file. Idempotent — safe to run again on an existing data directory.
python ca_server.py init [options]
| Option | Description |
|---|---|
--ca-key <path> | Import an existing CA private key (PEM) |
--ca-cert <path> | Import an existing CA certificate (PEM) |
--ca-password-file <path> | File containing the password to decrypt the imported key |
On first run, a random registration seed is generated and printed. Keep it secure.
register
Start the RA registration listener on port 5001 (clear mode). Waits for an RA node to complete the handshake, issues it a certificate, then exits.
python ca_server.py register
Run this command every time a new RA needs to be registered. The RA operator must have the seed printed by init.
listen
Start the CA operations listener on port 5000 (TLS mode).
python ca_server.py listen [--host <ip>] [--port <int>]
| Option | Default | Description |
|---|---|---|
--host <ip> | 127.0.0.1 | Bind address |
--port <int> | 5000 | Port number |
The RA must already be registered before starting listen.
start
Auto-bootstrap mode — the Docker default entrypoint. On first boot:
- Runs
initif not already done - Starts both the registration listener (port 5001) and the CA listener (port 5000) concurrently
On subsequent boots, skips init and starts both listeners directly.
python ca_server.py start
Requires UPKI_CA_SEED environment variable when a registration is needed.
Environment variables
All environment variables override the equivalent CLI options:
| Variable | CLI equivalent | Description |
|---|---|---|
UPKI_DATA_DIR | --path | Data directory path |
UPKI_CA_SEED | — | Registration seed (used by start) |
UPKI_CA_HOST | --host | ZMQ bind address |
UPKI_CA_KEY_FILE | --ca-key | Path to existing CA private key |
UPKI_CA_CERT_FILE | --ca-cert | Path to existing CA certificate |
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Configuration or storage error |
2 | Signal received (SIGTERM/SIGINT) — normal shutdown |