Skip to main content

Command Line Interface

At a Glance#

  • For setting up an HTTP server, whether for internal use, over the open internet, or both, we recommend using our dockerized HTTP server. Instructions below
  • Instructions for building manually can be found on the main Installation page
  • See the Examples section below for automation and testing building blocks.

Installation#

Docker#

The HTTP server is containerised and available under ghcr.io/spruceid/didkit-cli.

You can use the Docker image as a CLI:

$ docker run ghcr.io/spruceid/didkit-cli:latest --help

Note: You can pass JWKs either by sharing a volume with docker run --volume, or by passing the JWK directly with docker run -e JWK=$MY_JWK or docker run didkit-http --jwk $MY_JWK.

See the repo's Dockerfile for further details.

Syntax#

Each command is called in the form: didkit help, didkit generate-ed25519-key, etc.

help#

Output help about didkit and its subcommands.

generate-ed25519-key#

Generate a Ed25519 keypair and output it in JWK format.

key-to-did#

Given a JWK, output the corresponding did:key.

Currently, this only supports Ed25519 keys.

key-to-verification-method#

Given a Ed25519 JWK, output the corresponding did:key verificationMethod.

Options#

  • -k, --key-path <file> (required, conflicts with jwk): Filename of JWK file
  • -j, --jwk <jwk> (required, conflicts with key-path): JWK.

vc-issue-credential#

Issue a verifiable credential. Reads credential on stdin, constructs a linked data proof to add to the credential, and outputs the resulting verifiable credential.

Corresponds to /issue/credentials in vc-http-api.

The proof type is set automatically based on the key file provided. JWK parameters besides the cryptographic components, such as kid (Key ID), are ignored currently. For an RSA key, the alg (Algorithm) parameter is ignored and RS256 is used for it, for RsaSignature2018.

Options#

Options besides --key-path correspond to linked data proof options as specified in ld-proofs and vc-http-api.

  • -C, --challenge <challenge> - challenge property of the proof
  • -c, --created <created> - created property of the proof. ISO8601 datetime. Defaults to the current time.
  • -d, --domain <domain> - domain property of the proof
  • -k, --key-path <key> (required, conflicts with jwk): Filename of JWK for signing.
  • -j, --jwk <jwk> (required, conflicts with key-path): JWK for signing.
  • -p, --proof-purpose <proof-purpose> proofPurpose property of the proof.
  • -v, --verification-method <verification-method>verificationMethod property of the proof. URI for proof verification information, e.g. a public key identifier.

Supported JWK key types#

  • RSA
  • OKP (curve: Ed25519)

vc-verify-credential#

Verify a verifiable credential. Reads verifiable credential on standard input, and outputs verification result. Returns exit status zero if credential successfully verified, or non-zero if errors were encountered.

Corresponds to /verify/credentials in vc-http-api.

Options#

Options are linked data proof options as specified in ld-proofs and vc-http-api. If there is more than one proof present, at least one must pass all the requirements passed in the options.

  • -C, --challenge <challenge> - The challenge property of the proof must equal this value.
  • -c, --created <created> - The created property of the proof must be on or after the given ISO8601 datetime. Defaults to the current time.
  • -d, --domain <domain> - The domain property of the proof must equal the given value.
  • -p, --proof-purpose <proof-purpose> - The proofPurpose property of the proof must equal this value.
  • -v, --verification-method <verification-method> - The verificationMethod property of the proof must equal this value.

Supported proof types#

Output#

The verification result output is a VerificationResult JSON object as specified in vc-http-api:

{
"checks": [],
"warnings": [],
"errors": []
}

Verification result properties:

  • checks - Array of strings indicating checks completed on the credential.
  • warnings - Array of warnings encountered during validation or verification.
  • errors - Array of strings indicating errors encountered during validation or verification. If errors is empty, the credential is verified.

vc-issue-presentation#

Issue a verifiable presentation. Reads presentation on stdin, generates proof to add to it, and outputs the resulting verifiable presentation.

Corresponds to /prove/presentations in vc-http-api.

Options are the same as for vc-issue-credential.

vc-verify-presentation#

Verify a verifiable presentation. Reads verifiable presentation on stdin, and outputs verification result. Returns exit status zero if presentation successfully verified, or non-zero if errors were encountered.

Corresponds to /verify/presentations in vc-http-api.

Options and output format are the same as for vc-verify-credential.

Addition configuration#

Outbound Proxy#

You can set the environment variable HTTP_PROXY to have DIDKit use a proxy. Both HTTP and SOCKS protocols are supported.

Examples#

ToolExample
Core CLI syntaxExample script
Batching, AutomationExample automation script