CLI

The cosign CLI is a Cobra command tree. The entry point is cmd/cosign/main.go; the full command list is registered in cmd/cosign/cli/commands.go::New().

Anatomy of a cosign invocation

graph TD
    A[main.go] -->|fix POSIX flags| B[cli.New]
    B -->|registers ~32 subcommands| C[cobra.Command tree]
    C -->|cmd.Execute| D[Subcommand RunE]
    D -->|builds KeyOpts| E[options.KeyOpts]
    D -->|calls into| F[pkg/* libraries]
    F -->|side effects| G[Registry / Fulcio / Rekor / TSA]
    F -->|stderr UI| H[internal/ui]
    A -->|errors.As CosignError| I[os.Exit code]

main.go rewrites old Unix-style single-dash long flags (-output) into POSIX --output and warns about them, then runs cli.New().Execute(). If a subcommand returns a *cosignError.CosignError, the exit code is taken from that error (see cmd/cosign/errors/).

Subcommand groups

Cosign's commands cluster into a few logical groups. Each section below links to a more detailed page.

Group	Commands	Page
Signing	sign, sign-blob, attest, attest-blob	cli/signing-commands.md
Verification	verify, verify-attestation, verify-blob, verify-blob-attestation	cli/verification-commands.md
Key & cert management	generate-key-pair, import-key-pair, public-key, piv-tool, pkcs11-tool, login	cli/key-and-cert-management.md
OCI / artifact ops	attach, download, upload, copy, clean, triangulate, tree, save, load, manifest, dockerfile, generate	cli/oci-and-attachment-commands.md
Trust & infrastructure	initialize, trusted-root, signing-config, bundle, env, version, completion, debug	covered inline in cli/index.md below

Trust & infrastructure commands

These don't fit cleanly into a sign/verify group:

• cosign initialize (cmd/cosign/cli/initialize.go) — pulls or refreshes the TUF trusted_root.json (Fulcio CA, Rekor key, CT key, TSA chain). Run it once before air-gapping the verifier.
• cosign trusted-root create (cmd/cosign/cli/trustedroot.go) — assemble a trusted_root.json from local files (Fulcio chain PEM, Rekor public key, CT log key, TSA chain PEM, valid-from/until). Used by operators of private Sigstore instances.
• cosign signing-config create (cmd/cosign/cli/signingconfig.go) — build a SigningConfig JSON specifying which Fulcio/Rekor/TSA URLs to use. Pairs with cosign sign --signing-config.
• cosign bundle create (cmd/cosign/cli/bundle.go) — pack an existing detached .sig + .cert + Rekor entry into a Sigstore protobuf bundle.
• cosign env (cmd/cosign/cli/env.go) — print every cosign-known environment variable, its description, whether it's set, and whether it's marked sensitive. Walks the registry in pkg/cosign/env/env.go.
• cosign version — produced by sigs.k8s.io/release-utils/version (with a starwars ASCII-art font, see cmd/cosign/cli/commands.go). Supports --json. The exact format is documented in CLI.md.
• cosign completion — bash/zsh/fish/powershell completion (cmd/cosign/cli/completion.go).
• cosign debug — operator-debugging command (cmd/cosign/cli/debug.go). Currently dumps registry interactions for a given image.
• cosign login — registry auth, delegated to crane auth login.

Global flags

Defined in cmd/cosign/cli/options/root.go as RootOptions:

• --output-file — redirect stdout to a file (handy when scripting).
• -d, --verbose — enable debug logs from go-containerregistry.
• --timeout — global per-command timeout.

Where to read

• cmd/cosign/cli/commands.go — full subcommand registry; great as a top-level index.
• cmd/cosign/cli/options/ — every flag the CLI accepts.
• doc/cosign.md and friends — auto-generated reference pages, regenerated by make docgen.

Key source files

File	Purpose
cmd/cosign/main.go	Process entry, POSIX flag normalization, exit-code mapping
cmd/cosign/cli/commands.go	Cobra root, subcommand registration
cmd/cosign/cli/options/key.go	KeyOpts struct shared between sign / verify / blob / attest
cmd/cosign/cli/options/sign.go	All cosign sign flags
cmd/cosign/cli/options/verify.go	All cosign verify flags
cmd/cosign/cli/templates/templates.go	Custom Cobra usage / help formatting