Inspect a Running GnuPG Agent Safely with gpg-connect-agent

You will finish with a repeatable way to send Assuan commands to the running GnuPG agent, inspect its response, and stop the client cleanly. The examples use GnuPG 2.4.4 from the installed gpgconf package version 2.4.4-2ubuntu17.6.

Allow about ten minutes. You need a shell and the GnuPG utilities already installed. This guide uses read-only queries and local variables. It does not edit key material, change agent configuration, clear history, or restart a daemon. Some options can start a daemon automatically, so the examples make that choice visible.

1. Confirm the installed client

Start by checking the executable rather than assuming which GnuPG release is present:

$ gpg-connect-agent --version
gpg-connect-agent (GnuPG) 2.4.4
...

The manpage installed here is dated 25 January 2024 and describes GnuPG 2.4.4. Options and daemon behaviour can differ between releases, so keep this version in your notes when a script will run on more than one machine.

2. Send one harmless command

gpg-connect-agent reads Assuan commands from standard input and writes replies to standard output. The local /echo control command is a useful first test because it does not ask the agent to perform a cryptographic operation:

$ printf '%s\n' '/echo checkpoint' '/bye' | gpg-connect-agent --no-autostart
checkpoint

--no-autostart tells the client not to start the agent if it is not already running. That makes this a genuine availability check, rather than a command that silently changes the session state by launching a daemon. /bye ends the connection; it is preferable to leaving an interactive session waiting for more input.

Capture the exit status immediately when a script needs to act on failure:

if printf '%s\n' '/echo checkpoint' '/bye' | gpg-connect-agent --no-autostart; then
    printf '%s\n' 'gpg-connect-agent completed'
else
    status=$?
    printf 'gpg-connect-agent failed with status %s\n' "$status" >&2
    exit "$status"
fi

3. Inspect the interactive command set

Run the client without a pipe when you want to explore. Type one command per line, then finish with /bye:

$ gpg-connect-agent --no-autostart
/help
/serverpid
/bye

/help lists the control commands understood by the client. /serverpid asks the connected server for its process ID and stores it for internal use. It may produce no useful value when there is no agent to answer, which is why the first probe uses --no-autostart and a harmless echo. A failed connection is an operational result, not proof that the agent is misconfigured.

Use /serverpid only as an observation. Do not turn the returned number into a blanket permission to kill a process. Agent ownership, session state and the impact on applications using the agent still need checking before any service action.

4. Put a known command sequence in a file

For a check that will be repeated, keep the commands in a small file and pass it with --run. The file is read at startup, then normal input continues:

script_file=/tmp/gpg-connect-agent-check.txt
umask 077
printf '%s\n' \
    '/echo before-substitution' \
    '/let marker checkpoint' \
    '/subst' \
    '/echo $marker' \
    '/bye' > "$script_file"

gpg-connect-agent --no-autostart --run "$script_file"
status=$?
rm -f "$script_file"
exit "$status"

Expected output is:

before-substitution
checkpoint

/let creates a client-side variable. Variable replacement is disabled by default, so the example enables it explicitly with /subst. This order matters: putting /subst before the assignment is clearer, but the assignment still exists before the later echo. The temporary file contains commands, not secrets; use a protected directory and remove it after the run anyway.

The shell command above changes state only by creating and removing its temporary command file. If a run stops before cleanup, remove that exact file with rm -f /tmp/gpg-connect-agent-check.txt after confirming it is the file you created. Never place a private key, passphrase or other secret in a command file or on this command line.

5. Choose connection and decoding options deliberately

The default connection targets the running GnuPG agent using the current GnuPG home directory, normally ~/.gnupg. Use --homedir DIR only when you have a deliberate separate configuration directory:

$ printf '%s\n' '/bye' | gpg-connect-agent --no-autostart --homedir /path/to/gnupg-home

Replace /path/to/gnupg-home with a real directory you control. An incorrect home directory can make a healthy agent appear absent. Do not use sudo as a first troubleshooting step: running as another user changes the home directory and socket context, and can create ownership problems.

For an Assuan-compatible service that is not the normal agent, --raw-socket SOCKET connects directly to the named socket and skips the normal initialisation and environment checks. Treat a socket path as a security boundary: verify its owner and purpose before connecting. --exec PROGRAM ARG... instead runs a program as the Assuan server. The manpage says command-line options cannot be used in that mode, so keep it separate from ordinary agent checks.

--hex prints data lines in hexadecimal with an ASCII representation, while --decode removes percent escapes and ensures data lines start with D . These are output formats, not encryption. Use them when a protocol trace needs inspection, and do not paste the resulting output into a public issue if it may contain identifying data.

6. Keep automation quiet and bounded

Use --quiet when a wrapper only needs the exit status. Use --unbuffered when another process must receive input and output without standard buffering. Use --no-history for interactive work where command history should not be read or written. These options do not grant extra access and do not replace normal file-permission controls.

If a script unexpectedly starts an agent, add --no-autostart and handle the failure explicitly. If the agent is deliberately allowed to start, document that operational choice and check which user and GNUPGHOME it will use. Avoid --chuid unless you are already root and have a specific reason to run the client as another account; it changes identity and environment handling.