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.