CLI reference¶

Command reference for sigillum. Run sigillum <command> --help for the authoritative, always-current flag set — the pages here mirror it and add the defaults, failure modes and flag combinations that --help has no room for.

The commands sigillum exists for¶

sign and keys are attached from gitlab.com/phpboyscout/go/signing-cli as top-level commands rather than reimplemented, which is the point of sigillum existing separately from gtb.

decrypt and certificate are sigillum's own, in pkg/cmd. The split matters when something goes wrong: a signing defect belongs upstream in signing-cli, a decryption defect belongs in this repository.

Which framework built-ins are present¶

sigillum is generated from go-tool-base, so it also carries part of the framework's command set. What is actually there, as sigillum --help reports:

init and mcp are disabled in this tool and do not appear. They are switched off in the root command's feature set, so no flag or configuration key brings them back. Some framework help text still mentions init — sigillum config --help suggests running init <subsystem> for guided reconfiguration — and that suggestion does not apply here.

Global flags¶

Registered on the root command; available to every subcommand.

Why --output means two different things¶

The global --output selects an output format. But sign, every keys subcommand, decrypt and certificate all define their own local --output, which is a file path, and a local flag shadows the global one — those commands do not even list the global --output in their help.

decrypt is the one where this bites hardest. sigillum decrypt --output json … does not produce JSON diagnostics; it writes the decrypted vulnerability report to a file named json in the working directory.

So sigillum --output json config list prints JSON, while sigillum sign --output json … writes a signature to a file named json. There is no way to get JSON output from the signing commands; they report through structured log lines on stderr instead.

Backends¶

--backend selects a key service compiled into the binary, activated by blank imports in the main package. There are two independent registries and the same flag name selects from whichever the command needs:

They are separate registries because the operations are: signing needs a key that signs, and decrypt and certificate need one that performs ECDH key agreement. A name present in one is not automatically present in the other — they happen to ship the same two today, but that is a fact about this build rather than a rule.

--backend is required for every one of these commands. It defaults only when exactly one backend is compiled in, which is no longer the case for either registry — and a default whose meaning changes as backends are linked into the binary is a worse thing to rely on than an explicit flag.

Signing backends¶

An unrecognised name fails immediately and names the alternatives:

"vault" (available: aws-kms, local): unknown signing backend

aws-kms resolves credentials from the AWS SDK default chain — environment variables, ~/.aws/credentials, IAM Roles Anywhere, OIDC web identity. sigillum adds nothing of its own: no --profile and no assume-role step. Set AWS_PROFILE, or export session credentials, before invoking it.

local reads unencrypted PEMs only. Encrypted PKCS#8 is refused, and so is ECDSA — see What sigillum does not do.

A regulated build can drop the AWS KMS blank import and rebuild; linker dead-code elimination then keeps that SDK out of the binary entirely.

Which key algorithm do I need?¶

The signature format decides the key algorithm, and the two do not overlap:

keys mint builds an OpenPGP entity, so it is RSA-only for the same reason. keys minisign derives a minisign public key, so it is Ed25519-only. A project publishing both signature kinds runs two keys.

Exit codes¶

A signal cancels the command's context so it can shut down gracefully; a second signal force-exits immediately.

Which stream does output go to?¶

Diagnostics — every error, and the INFO lines that report fingerprints and output paths — go to stderr. Only command output proper goes to stdout, such as the bare public key from keys minisign. That split is what makes sigillum keys minisign … > key.b64 produce a usable file rather than an empty one.