Inspect a Running Agent with gpg-connect-agent

gpg-connect-agent gives you a repeatable way to send Assuan commands to the running GnuPG agent, read 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 is read-only. It does not edit key material, change agent configuration, clear history, or restart a daemon.
• Watch the autostart. 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, making this a genuine availability check rather than a command that silently launches 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.

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.

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 the placeholder 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.
• --raw-socket SOCKET connects directly to a non-standard Assuan-compatible service, skipping 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 hex or decode output 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

• --quiet for a wrapper that only needs the exit status.
• --unbuffered when another process must receive input and output without standard buffering.
• --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.