CLI Reference¶
The diogenes CLI provides command-line access to all trust management operations: key management, document signing, endorsements, project entities, trust configuration, institutional designation, federation, and witnessing.
Installation¶
The CLI is available as the diogenes command after installation.
Command Groups¶
diogenes key -- Key Management¶
Manage cryptographic keys and endorsements.
key register¶
Generate a key pair and register the public key on the transparency log.
diogenes key register \
--pseudonym "Alice Scholar" \
--algorithm ed25519 \
--expiry-days 365 \
--password "secret" \
--server-url http://localhost:8000
| Option | Required | Default | Description |
|---|---|---|---|
--pseudonym |
Yes | -- | Human-readable name for the key |
--algorithm |
No | ed25519 |
Key algorithm: ed25519, ecdsa-p256, or rsa-2048 |
--expiry-days |
No | 365 |
Key expiry in days |
--password |
Yes | -- | Password to encrypt the local private key |
--server-url |
No | https://localhost:8002 |
Diogenes server URL |
key endorse¶
Issue an endorsement offer from one key to another. Supports all endorsement categories.
diogenes key endorse \
--fingerprint <your-fp> \
--target <target-fp> \
--category human_attestation \
--password "secret" \
--server-url http://localhost:8000
| Option | Required | Description |
|---|---|---|
--fingerprint |
Yes | Endorser's key fingerprint |
--target |
Yes | Target key fingerprint to endorse |
--category |
Yes | One of: human_attestation, institutional_endorsement, institutional_designation, federation_operator |
--name |
Conditional | Institution name (required for institutional_designation) |
--domain |
Conditional | Institution domain (required for institutional_designation) |
--role |
Conditional | Maintainer role (required for institutional_endorsement, e.g. release-signer) |
--valid-until |
No | Endorsement expiry date (YYYY-MM-DD) |
--password |
Yes | Password for the endorser key |
key accept-offer¶
Accept a pending endorsement offer.
key list-offers¶
List endorsement offers for a key.
key list¶
List keys stored in the local keystore.
diogenes project -- OSS Project Entities¶
Manage open-source software project entities and their maintainers.
project init¶
Initialize a new OSS project entity with key generation.
diogenes project init \
--name "my-project" \
--ecosystem npm \
--repo-url "https://github.com/org/repo" \
--package-name "my-package" \
--homepage "https://my-project.dev" \
--password "secret"
| Option | Required | Description |
|---|---|---|
--name |
Yes | Project name (used as pseudonym) |
--ecosystem |
Yes | Package ecosystem (npm, pypi, etc.) |
--repo-url |
Yes | Repository URL |
--package-name |
Yes | Package name in the ecosystem |
--homepage |
Yes | Project homepage URL |
--algorithm |
No | Key algorithm (default: ed25519) |
--password |
Yes | Password to encrypt the private key |
--expiry-days |
No | Key expiry in days (default: 365) |
project add-maintainer¶
Issue an institutional endorsement for a maintainer key.
diogenes project add-maintainer \
--fingerprint <project-fp> \
--target <maintainer-fp> \
--role release-signer \
--password "secret"
project remove-maintainer¶
Withdraw an institutional endorsement for a maintainer.
project endorse¶
Issue an endorsement offer for a target key in a project context.
project withdraw¶
Withdraw an existing endorsement.
diogenes trust -- Trust Configuration¶
Manage trust configuration profiles that control how Layer 3 verification evaluates trust.
trust use-profile¶
Activate a named reference trust profile.
Available profiles:
| Profile | Description |
|---|---|
community-default |
Balanced defaults for community use |
openssf-strict |
Strict settings for OpenSSF compliance |
permissive |
Relaxed settings for development/testing |
trust list-profiles¶
List all available reference trust profiles.
diogenes operator -- System Bootstrap¶
Operator commands for bootstrapping the trust system, designating institutions, and managing federation and witnesses.
Operator Only
These commands require access to the operator key. They are used during system bootstrap and ongoing administration.
operator fingerprint¶
Print the operator's own key fingerprint.
operator designate-institution¶
Designate a key as an institutional key. Issues an active x-diogenes:institutional_designation endorsement directly (bypasses offer/accept flow).
operator authorize-federation¶
Authorize a key as a federation follower.
operator authorize-witness¶
Authorize a key as a log witness.
operator set-profile¶
Create or update an operator profile for federation or witness operators.
operator list-institutions¶
List all designated institutional keys.
operator list-followers¶
List authorized federation followers.
operator list-witnesses¶
List known witnesses and their proof counts.
operator reset-db¶
Drop all tables and recreate the schema. Requires confirmation.
diogenes institution -- Institution Profiles¶
Manage institution profiles for designated institutional keys.
institution set-profile¶
Create or update an institution profile.
diogenes institution set-profile \
--fingerprint <institution-fp> \
--display-name "MIT" \
--domain "mit.edu" \
--description "Massachusetts Institute of Technology" \
--website "https://mit.edu" \
--contact-email "trust@mit.edu" \
--password "secret"
| Option | Required | Description |
|---|---|---|
--fingerprint |
Yes | Institution key fingerprint (must own this key) |
--display-name |
Yes | Institution display name |
--domain |
Yes | Institution domain |
--description |
No | Free-text description |
--website |
No | Institution website URL |
--contact-email |
No | Public contact email |
--logo-url |
No | URL to institution logo |
--password |
Yes | Password for the institution key |
institution show¶
Display an institution's profile and designations.
diogenes witness -- Log Witnessing¶
Witness-side tools for transparency log monitoring and consistency proof submission.
witness fingerprint¶
Print the local witness key fingerprint. Generates an Ed25519 key on first use at ~/.diogenes/witness/witness.pem.
witness submit¶
Fetch the current tree head from the server, sign a consistency proof, and submit it.
The baseline (previous tree size and root) is stored locally in ~/.diogenes/witness/state.json. The first submission uses size=0.
witness status¶
Report whether this witness is currently authorized by the operator.
witness history¶
List proofs this witness has recently submitted.
Environment Variables¶
| Variable | Description |
|---|---|
DIOGENES_SERVER_URL |
Default server URL for CLI commands |
DIOGENES_KEY_PASSWORD |
Default password for key operations |