Skip to content

Shell

Spawns a process in a pseudo terminal (pty) and replicates it locally in a similar manner to ssh.

distant shell

Flags

  • --current-dir <DIR>: provide an alternative directory to use as the current working directory for the spawned shell. By default, the shell will inherit the working directory of the server.

  • --environment <ENV>: provide environment variables to be available in the shell when spawned. These are comma-separated in a KEY=VALUE format.

Examples

Using a custom shell

By default, this will use the default shell associated with the server, usually $SHELL on Unix platforms or %ComSpec% on Windows.

This can be changed by providing an alternative program to run, which could be some other process such as python:

distant shell -- python

Supplying custom environment variables

Similar to other multi-option flags, the environment option takes a collection of environment variables in the form of KEY=VALUE:

distant shell --environment 'VAR="hello world",KEY=value'
distant shell --help 
Specialized treatment of running a remote shell process

Usage: distant shell [OPTIONS] [-- <CMD>...]

Arguments:
  [CMD]...  Optional command to run instead of $SHELL

Options:
      --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]
      --connection <CONNECTION>      Specify a connection being managed
      --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)
      --current-dir <CURRENT_DIR>    Alternative current directory for the remote process
      --environment <ENVIRONMENT>    Environment variables to provide to the shell [default: ]
  -h, --help                         Print help