search..
No manual entry for -- in section 1
GPG-CONNECT-AGENT(1)	     GNU Privacy Guard 2.4	   GPG-CONNECT-AGENT(1)

NAME
       gpg-connect-agent - Communicate with a running agent

SYNOPSIS
       gpg-connect-agent [options][commands]

DESCRIPTION
       The  gpg-connect-agent  is  a  utility  to  communicate	with  a running
       gpg-agent.  It is useful to check out the  commands  gpg-agent  provides
       using  the Assuan interface.  It might also be useful for scripting sim-
       ple applications.  Input is expected at stdin and output gets printed to
       stdout.

       It is very similar to running gpg-agent in server mode; but here we con-
       nect to a running instance.

       The following options may be used:

       --dirmngr
	      Connect to a running directory manager (keyserver client) instead
	      of to the gpg-agent.  If a dirmngr is not running, start it.

       --keyboxd
	      Connect to a running keybox daemon instead of to	the  gpg-agent.
	      If a keyboxd is not running, start it.

       -S
       --raw-socket name
	      Connect  to  socket name assuming this is an Assuan style server.
	      Do not run any special  initializations  or  environment	checks.
	      This  may	 be used to directly connect to any Assuan style socket
	      server.

       -E
       --exec Take the rest of the command line as a program and it's arguments
	      and execute it as an Assuan server. Here is  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.

       -v
       --verbose
	      Output additional information while running.

       -q

       --quiet
	      Try to be as quiet as possible.

       --homedir dir
	      Set  the name of the home directory to dir. If this option is not
	      used, the home directory defaults to `~/.gnupg'.	It is only rec-
	      ognized 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  en-
	      try 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  con-
	      sidered, all other ways to set a home directory are ignored.

       --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.  To  override  the
	      latter the option --homedir can be used.	This option has only an
	      effect  when used on the command line.  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.

       --no-autostart
	      Do not start the gpg-agent or the dirmngr if it has not yet  been
	      started.

       --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.

       --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.  Note that the pipe symbol (|) is used for a regres-
	      sion test suite hack and may thus not be used in the file name.

       --dirmngr-program file
	      Specify  the  directory  manager (keyserver client) program to be
	      started if none is running.  This has only an effect if used  to-
	      gether with the option --dirmngr.

       --keyboxd-program file
	      Specify  the  keybox daemon program to be started if none is run-
	      ning.  This has only an effect if used together with  the	 option
	      --keyboxd.

       -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.

       -s
       --subst
	      Run the command /subst at startup.

       --hex  Print  data lines in a hex format and the ASCII representation of
	      non-control characters.

       --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.

       -u
       --unbuffered
	      Set  stdin  and stdout into unbuffered I/O mode.	This this some-
	      times useful for scripting.

CONTROL COMMANDS
       While reading Assuan commands, gpg-agent also allows a few special  com-
       mands to control its operation.	These control commands all start with a
       slash (/).

       /echo args
	      Just print args.

       /let name value
	      Set  the	variable name to value.	 Variables are only substituted
	      on the input if the /subst has been used.	 Variables  are	 refer-
	      enced by prefixing the name with a dollar sign and optionally in-
	      clude  the  name in curly braces.	 The rules for a valid name are
	      identically to those of the standard bourne shell.  This	is  not
	      yet  enforced  but  may  be  in the future.  When used with curly
	      braces no leading or trailing white space is allowed.

	      If a variable is not found, it is searched in the environment and
	      if found copied to the table of variables.

	      Variable functions are available: The name of the	 function  must
	      be  followed by at least one space and the at least one argument.
	      The following functions are available:

	      get    Return a value described by the argument.	Available argu-
		     ments 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.  Command  /serverpid
			    must have been given to return a useful value.

	      unescape args
		     Remove  C-style  escapes from args.  Note that \0 and \x00
		     terminate the returned string implicitly.	The  string  to
		     be converted are the entire arguments right behind the de-
		     limiting space of the function name.

	      unpercent args
	      unpercent+ args
		     Remove  percent  style  escaping from args.  Note that %00
		     terminates the string implicitly.	The string to  be  con-
		     verted  are the entire arguments right behind the delimit-
		     ing space of the function name. unpercent+ also maps  plus
		     signs to a spaces.

	      percent args
	      percent+ args
		     Escape the args using percent style escaping.  Tabs, form-
		     feeds, 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.
		     Return the gpg-error error code, error source or a format-
		     ted string with the error code and error source.

	      +
	      -
	      *
	      /
	      %	     Evaluate all arguments as long integers using  strtol  and
		     apply  this  operator.  A division by zero yields an empty
		     string.

	      !
	      |
	      &	     Evaluate all arguments as long integers using  strtol  and
		     apply the logical operators NOT, OR or AND.  The NOT oper-
		     ator works on the last argument only.

       /definq name var
	      Use  content  of	the variable var for inquiries with name.  name
	      may be an asterisk (*) to match any inquiry.

       /definqfile name file
	      Use content of file for inquiries with name.  name may be an  as-
	      terisk (*) to match any inquiry.

       /definqprog name prog
	      Run  prog for inquiries matching name and pass the entire line to
	      it as command line arguments.

       /datafile name
	      Write all data lines from the server to the file name.  The  file
	      is  opened for writing and created if it does not exists.	 An ex-
	      isting file is first truncated to 0.  The	 data  written	to  the
	      file  fully decoded.  Using a single dash for name writes to std-
	      out.  The file is kept open until a new file is  set  using  this
	      command or this command is used without an argument.

       /showdef
	      Print all definitions

       /cleardef
	      Delete all definitions

       /sendfd file mode
	      Open  file  in mode (which needs to be a valid fopen mode string)
	      and send the file descriptor to the server.  This is usually fol-
	      lowed by a command like INPUT FD to  set	the  input  source  for
	      other commands.

       /recvfd
	      Not yet implemented.

       /open var file [mode]
	      Open  file  and assign the file descriptor to var.  Warning: This
	      command is experimental and might change in future versions.

       /close fd
	      Close the file descriptor fd.  Warning: This command  is	experi-
	      mental and might change in future versions.

       /showopen
	      Show a list of open files.

       /serverpid
	      Send  the	 Assuan command GETINFO pid to the server and store the
	      returned PID for internal purposes.

       /sleep Sleep for a second.

       /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  dis-
	      abled  unless  the command line option --subst has been used.  If
	      /subst as been enabled once, leading whitespace is  removed  from
	      input lines which makes scripts easier to read.

       /while condition
       /end   These  commands provide a way for executing loops.  All lines be-
	      tween 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:

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

       /if condition
       /end   These commands provide a	way  for  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.

       /run file
	      Run commands from file.

       /history --clear
	      Clear the command history.

       /bye   Terminate the connection and the program.

       /help  Print a list of available control commands.

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.

GnuPG 2.4.7			   2024-11-22		   GPG-CONNECT-AGENT(1)