GPG-CONNECT-AGENT(1)

okay so real talk: this is gpg-connect-agent(1) from GNU Privacy Guard 2.4 — yes, that GnuPG, the one your crypto-nerd friend keeps telling you about 💅 — and it's genuinely one of the most useful little tools in the whole suite. Buckle up bestie 🎀

🌸 NAME 🌸

gpg-connect-agent — the way to Communicate with a running agent. That's it. That's the whole vibe. 🫶

✨ SYNOPSIS ✨

gpg-connect-agent [options][commands]

(yes, [options][commands] is written all squished together like that, no space — iconic, don't touch it 💀)

🦋 DESCRIPTION 🦋

Okay so picture this: gpg-connect-agent is a utility to communicate with a running gpg-agent. That's the whole main character energy right there 👑

It's genuinely useful for checking out all the commands gpg-agent provides using the Assuan interface — like, you can literally poke at the agent and see what it's made of. It might also be useful for scripting simple applications (key word simple, goblins, don't go building your whole startup on this 🙈).

The flow is: input is expected at stdin, and output gets printed to stdout. Clean, classic, no notes. ✨

It's very similar to running gpg-agent in server mode — except here we connect to a running instance. That distinction is lowkey the whole point, iykyk.

The following options may be used:

🎀 THE OPTIONS 🎀

• --dirmngr — Connect to a running directory manager (keyserver client) instead of to the gpg-agent. And if a dirmngr is not running? It just starts it. Problem solved, slay. ✨
• --keyboxd — Connect to a running keybox daemon instead of to the gpg-agent. If a keyboxd is not running, it starts it. Same energy, different daemon 💅
• -S, --raw-socket name — Connect to socket name assuming this is an Assuan style server. Do not run any special initializations or environment checks — it goes straight in, no vibe check, no small talk. This may be used to directly connect to any Assuan style socket server. Raw, unfiltered, main character 🦋
• -E, --exec — Take the rest of the command line as a program and it's arguments and execute it as an Assuan server. Here's how you would run gpgsm:

gpg-connect-agent --exec gpgsm --server

⚠️ Note that you may not use options on the command line in this case. Because the rest of the command line is the program now, bestie. It's taken. It's booked. 💀

• -v, --verbose — Output additional information while running. For when you wanna know everything that's happening 🍓
• -q, --quiet — Try to be as quiet as possible. For when you wanna know nothing 🤫
• --homedir dir — Set the name of the home directory to dir. If this option is not used, the home directory defaults to ~/.gnupg. Important detail: it is only recognized when given on the command line. It also overrides any home directory stated through the environment variable GNUPGHOME or (on Windows systems) by means of the Registry entry HKCU\Software\GNU\GnuPG:HomeDir. 👑

On Windows systems it is possible to install GnuPG as a portable application. In this case only this command line option is considered — all other ways to set a home directory are ignored. Periodt. 💅

• --chuid uid — Change the current user to uid, which may either be a number or a name. This can be used from the root account to run gpg-connect-agent for another user. If uid is not the current UID, a standard PATH is set and the envvar GNUPGHOME is unset — and to override the latter, the option --homedir can be used. This option has only an effect when used on the command line. And heads up: this option has currently no effect at all on Windows. 🫠
• --no-ext-connect — When using -S or --exec, gpg-connect-agent connects to the Assuan server in extended mode to allow descriptor passing. This option makes it use the old mode instead. Retro vibes, but make it intentional 🌈
• --no-autostart — Do not start the gpg-agent or the dirmngr if it has not yet been started. You're on your own, babe 💀
• --no-history — In interactive mode the command line history is usually saved and restored to and from a file below the GnuPG home directory. This option inhibits the use of that file. No receipts, no trail 🙈
• --agent-program file — Specify the agent program to be started if none is running. The default value is determined by running gpgconf with the option --list-dirs.

⚠️ Real caveat: note that the pipe symbol (|) is used for a regression test suite hack and may thus not be used in the file name. Do not fight this, it's not worth it 😭

• --dirmngr-program file — Specify the directory manager (keyserver client) program to be started if none is running. This has only an effect if used together with the option --dirmngr. Teamwork, bestie 🫶
• --keyboxd-program file — Specify the keybox daemon program to be started if none is running. This has only an effect if used together with the option --keyboxd. Same deal, different daemon ✨
• -r file, --run file — Run the commands from file at startup and then continue with the regular input method. Note, that commands given on the command line are executed after this file. Order matters, always 🔥
• -s, --subst — Run the command /subst at startup. That's literally the whole thing. Short, sweet, iconic 🎀
• --hex — Print data lines in a hex format and the ASCII representation of non-control characters. For my hex girlies 🔢
• --decode — Decode data lines. That is to remove percent escapes but make sure that a new line always starts with a D and a space. Yes, the D and the space are non-negotiable 💅
• -u, --unbuffered — Set stdin and stdout into unbuffered I/O mode. This is sometimes useful for scripting. When you need it, you know 🌸

---

💅 CONTROL COMMANDS 💅

So while gpg-agent is out here reading Assuan commands, it also lets you slide in a few special commands to control the whole operation. These control commands all start with a slash (/). Periodt. 🎀

---

• /echo args — literally just prints args back at you. That's it. That's the whole job. Iconic minimalism. ✨
• /let name value — sets the variable name to value. Okay so important tea: variables are only substituted on the input if you've used /subst. You reference a variable by putting a dollar sign in front of the name, and you can optionally wrap the name in curly braces. The rules for what counts as a valid name are identical to those of the standard bourne shell — tho ngl, that's not yet enforced, but it may be in the future, so don't get too comfy. 👀 When you use curly braces, no leading or trailing white space is allowed.

If a variable isn't found, it gets searched in the environment, and if it's found there it gets copied over to the table of variables. Sneaky but slay. 🦋

Variable functions exist too! The name of the function must be followed by at least one space and at least one argument. Here's the lineup:

get — returns a value described by the argument. Available arguments are:

• cwd — the current working directory.
• homedir — the gnupg homedir.
• sysconfdir — GnuPG's system configuration directory.
• bindir — GnuPG's binary directory.
• libdir — GnuPG's library directory.
• libexecdir — GnuPG's library directory for executable files.
• datadir — GnuPG's data directory.
• serverpid — the PID of the current server. Heads up tho: the command /serverpid must have been given for this to return a useful value. No /serverpid, no useful vibe check. 💀

unescape args — removes C-style escapes from args. Note that \0 and \x00 terminate the returned string implicitly. The string being converted is the entire arguments right behind the delimiting space of the function name. 🧚

unpercent args / unpercent+ args — removes percent style escaping from args. Note that %00 terminates the string implicitly. The string being converted is the entire arguments right behind the delimiting space of the function name. unpercent+ also maps plus signs to spaces. Extra. 💅

percent args / percent+ args — escapes args using percent style escaping. Tabs, formfeeds, linefeeds, carriage returns and colons are escaped. percent+ also maps spaces to plus signs. 🌸

errcode arg / errsource arg / errstring arg — assume arg is an integer and evaluate it using strtol. Returns the gpg-error error code, the error source, or a formatted string with the error code and error source. 🎀

+ / - / * / / / % — evaluate all arguments as long integers using strtol, then apply this operator. A division by zero yields an empty string (so like, no crash, just vibes). 🔥

! / | / & — evaluate all arguments as long integers using strtol, then apply the logical operators NOT, OR or AND. The NOT operator works on the last argument only. Main character energy tbh. 👑

• /definq name var — uses the content of the variable var for inquiries with name. And name may be an asterisk (*) to match any inquiry. Wildcard queen. ⭐
• /definqfile name file — uses the content of file for inquiries with name. Again, name may be an asterisk (*) to match any inquiry.
• /definqprog name prog — runs prog for inquiries matching name, and passes the entire line to it as command line arguments. 🫶
• /datafile name — writes all data lines from the server to the file name. The file is opened for writing and created if it doesn't exist. An existing file is first truncated to 0. The data written to the file is fully decoded. Using a single dash for name writes to stdout. The file is kept open until a new file is set using this command, or until this command is used without an argument. 😭 (rip your previous file, fr fr)
• /showdef — prints all definitions.
• /cleardef — deletes all definitions. Clean slate, fresh start, new era. ✨
• /sendfd file mode — opens file in mode (which needs to be a valid fopen mode string) and sends the file descriptor to the server. This is usually followed by a command like INPUT FD to set the input source for other commands. 🦋
• /recvfd — not yet implemented. She's coming, bestie. Not yet, but she's coming. 🙈
• /open var file [mode] — opens file and assigns the file descriptor to var. > Warning: this command is experimental and might change in future versions. Handle with care! 💅
• /close fd — closes the file descriptor fd. > Warning: this command is experimental and might change in future versions. Same energy. 🎀
• /showopen — shows a list of open files. Peek behind the curtain. 👀
• /serverpid — sends the Assuan command GETINFO pid to the server and stores the returned PID for internal purposes. (Remember this one — /let's get serverpid needs it!) 💜
• /sleep — sleeps for a second. Take a lil nap. Self care. 😴
• /hex / /nohex — same as the command line option --hex. ⭐
• /decode / /nodecode — same as the command line option --decode. 🌈
• /subst / /nosubst — enable and disable variable substitution. It defaults to disabled unless the command line option --subst has been used. And here's a cute detail: if /subst has been enabled once, leading whitespace is removed from input lines, which makes scripts easier to read. You're welcome. 💖
• /while condition / /end — these commands give you a way to execute loops! All lines between the while and the corresponding end are executed as long as the evaluation of condition yields a non-zero value, or is the string true or yes. The evaluation is done by passing condition to the strtol function. Example time, bestie:

/subst
/let i 3
/while $i
  /echo loop counter is $i
  /let i ${- $i 1}
/end

Countdown loop, ate. 🔥

• /if condition / /end — these commands give you conditional execution. All lines between the if and the corresponding end are executed only if the evaluation of condition yields a non-zero value, or is the string true or yes. The evaluation is done by passing condition to the strtol function. Same rules, different drama. 🎀
• /run file — runs commands from file. Script girlie behavior. 📜
• /history --clear — clears the command history. No receipts, no evidence, we don't know her. 💀
• /bye — terminates the connection and the program. The exit. The farewell. The mic drop. 👋
• /help — prints a list of available control commands. When in doubt, ask for help — that's growth. 🫶

---

🌸 SEE ALSO 🌸

gpg-agent(1), scdaemon(1)

The full documentation for this tool is maintained as a Texinfo manual. If GnuPG and the info program are properly installed at your site, the command

info gnupg

should give you access to the complete manual including a menu structure and an index. Go read it, it's giving comprehensive. 📚✨

---

And that's the whole page, bestie! 🎉 This lil masterpiece is from GnuPG 2.4.9, dated 2025-02-19 — icon behavior, no notes. 💅👑💖