CLI Reference

scdaemon-se binary

Run with no arguments to start the Assuan server on stdin/stdout — this is how gpg-agent invokes it; you won’t normally run it this way by hand.

Flag Behavior
--export-public-key [--uid "Name <email>"] Export the public key in armored, GPG-importable format. Requires SCDAEMON_SE_ALLOW_MASTER=1 (see Security Model) or it refuses with an explanation and exits 1. Without --uid, a user ID is generated from your system full name / username.
--add-signing-card [--name <label>] Create an additional virtual card with a new Secure Enclave signing key (may prompt for Touch ID). Prints the new card’s serial, AID, and the exact gpg-connect-agent command to select it.
--list-cards List every card: serial, AID, role (primary (sign/decrypt/auth) or signing), and label if set.
--inspect Show every card’s key slots and whether their Secure Enclave key handles are present, using an existence-only Keychain check — this specific check never prompts for Touch ID or a Keychain password.
--remove-card <serial> --yes Delete an additional card and its Secure Enclave key. Irreversible, and breaks any subkey bound to it. Refuses without --yes (prints a warning instead). The primary card can never be removed this way.
--help Print usage and the environment variables below.

Environment variables

Variable Effect
SCDAEMON_SE_DEBUG Enables debug logging to stderr when set to any value (checked by presence, not by value — SCDAEMON_SE_DEBUG=1 and SCDAEMON_SE_DEBUG=anything both work). Payloads are redacted; see Architecture § Request flow.
SCDAEMON_SE_ALLOW_ENCRYPTION Truthy value (1, true, yes, or on, case-insensitive) allows creating the OPENPGP.2 decryption key. Off by default. See Security Model.
SCDAEMON_SE_ALLOW_MASTER Same truthy check; allows --export-public-key. Off by default. See Security Model.

Scripts

All paths are relative to the repository root.

Script Purpose Safe for a real, in-use setup?
scripts/setup.sh Build + configure gpg-agent.conf (see Installation). Yes
scripts/clear-secure-enclave.sh Uninstall/reset helper for the primary card and shared state (registry, key-pin store). Dry run by default — prints every specific Keychain item it found, by name, and deletes nothing until you pass --yes. --shadow-stubs (off by default) additionally removes scdaemon-se’s own GPG shadow key stubs, matched by keygrip against the key-pin store — another card’s stubs (e.g. a YubiKey’s) are identified and never touched. To remove one additional signing card instead, use scdaemon-se --remove-card <serial> --yes (built into the daemon; refuses to touch the primary card). Yes — dry run is always safe; --yes performs exactly the printed plan. Like inspect-secure-enclave.sh below, even the dry run reads the card-registry and key-pin-store secret data (security ... -w) to list items by name, which can trigger a Keychain-password prompt.
scripts/inspect-secure-enclave.sh Read-only report combining scdaemon-se --inspect with the raw Keychain entries for the scdaemon-se service. The card/slot summary never prompts, but the raw card-registry and legacy-metadata JSON dumps read actual Keychain secret data (security ... -w) and can trigger a Keychain-password prompt — despite this script’s own header comment claiming otherwise. If it appears to hang, check for a password dialog.
scripts/clear-test-artifacts.sh Sweeps up orphaned com.scdaemon-se.test.* Keychain services left behind when a test run is interrupted before its automatic teardown runs (see Development). Dry run by default — lists every orphaned service and its item count, deletes nothing until you pass --yes. Only ever touches services matching that test-only prefix; never the real "scdaemon-se" production service. Yes — dry run is always safe; --yes only ever deletes com.scdaemon-se.test.* services.
scripts/scdaemon-se-wrapper.sh A pre-built debug-logging wrapper: sets SCDAEMON_SE_DEBUG=1 and logs to ~/.local/share/scdaemon-se/debug-<date>.log (directory 0700, file 0600). Point scdaemon-program at this instead of the bare binary to get logs. Different from — and not created by — setup.sh’s own wrapper, which just execs the binary with no logging. Yes
scripts/test-setup.sh Developer/CI only. Kills all gpg daemons, then unconditionally deletes every Keychain entry under the scdaemon-se service — including your real keys if you have any — before creating a temporary GNUPGHOME. No — do not run this against a machine with real Secure Enclave keys you care about.
scripts/test-cleanup.sh Developer/CI only. Companion to test-setup.sh: removes the temporary GNUPGHOME and again unconditionally deletes every scdaemon-se Keychain entry. No, same reason.
scripts/test-e2e.sh Developer/CI only. Full sign/verify smoke test: calls test-setup.sh (see above), builds in debug, exports and imports a key, creates shadow stubs, signs, and verifies. No — inherits test-setup.sh’s Keychain wipe.
scripts/test-e2e-multicard.sh Interactive, but non-destructive. Builds, creates its own throwaway GNUPGHOME, binds the existing primary card’s signing key plus a newly-created second card as subkeys of a throwaway external master, signs with both, and removes only the throwaway second card on exit. Never wipes the Keychain service and never touches the primary card’s keys. Expects several Touch ID prompts to be approved interactively. Yes

If you need a disposable test environment without wiping your real keys, model it on test-e2e-multicard.sh rather than test-setup.sh.


scdaemon-se is licensed under the MIT License.

This site uses Just the Docs, a documentation theme for Jekyll.