Skip to content


Changes the active connection used by other commands when talking to a manager.

distant manager select 1234


  • --format <FORMAT>: determines how the response is printed. With json specified, the response will be printed in this form:

    { "type": "ok" }

    Any error encountered will be captured and printed in this form:

    { "type": "error", "msg": "..." }

Interactive Mode

If no connection id is provided, this command enters an interactive mode, where it provides a collection of choices and the user identifies which connection to make the active one.

JSON Format

When using format as json, interactive mode will print out available choices, the current selection (as a base-0 index), and a type field as a JSON object:

    "type": "select",
    "choices": ["distant://", "ssh://"],
    "current": 0

In response to the available choices, a JSON message needs to be sent in this form:

    "type": "selected",
    "choice": 1

The type field is required while the choice field is optional. The choice corresponds to the index of the choice within the choices field received earlier. If none is provided, the current selection is not changed.


All JSON comes in a single line format ending in a newline character. Responses are also expected to be sent as a single line containing all JSON and ending in a newline character.

distant manager select --help
Select the active connection

Usage: distant manager select [OPTIONS] [CONNECTION]

          Connection to use, otherwise will prompt to select

      --cache <CACHE>
          Location to store cached data

          [default: /home/runner/.cache/distant/cache.toml]

      --log-level <LOG_LEVEL>
          Log level to use throughout the application

          [possible values: off, error, warn, info, debug, trace]

  -f, --format <FORMAT>
          [default: shell]

          Possible values:
          - json:  Sends and receives data in JSON format
          - shell: Commands are traditional shell commands and output responses are inline with what is expected of a program's output in a shell

      --log-file <LOG_FILE>
          Path to file to use for logging

      --config <CONFIG_PATH>
          Configuration file to load instead of the default paths

      --unix-socket <UNIX_SOCKET>
          Override the path to the Unix socket used by the manager (unix-only)

      --windows-pipe <WINDOWS_PIPE>
          Override the name of the local named Windows pipe used by the manager (windows-only)

  -h, --help
          Print help (see a summary with '-h')