edgeport - v1.0.3
    Preparing search index...

    Interface SshSession

    A stateful SSH session.

    interface SshSession {
        "[asyncDispose]"(): PromiseLike<void>;
        chmod(
            path: string | string[],
            mode: string | number,
            opts?: { recursive?: boolean },
        ): Promise<void>;
        close(): Promise<void>;
        df(
            path?: string,
        ): Promise<
            {
                availKb: number;
                filesystem: string;
                mountedOn: string;
                sizeKb: number;
                usedKb: number;
                usePercent: number;
            }[],
        >;
        exec(command: string): Promise<ExecResult>;
        execStream(command: string): Promise<SshChannelHandle>;
        exists(path: string): Promise<boolean>;
        forwardOut(host: string, port: number): Promise<SshChannelHandle>;
        mkdirp(path: string, opts?: { mode?: number }): Promise<void>;
        readTextFile(path: string): Promise<string>;
        rekey(): Promise<void>;
        rm(
            path: string | string[],
            opts?: { force?: boolean; recursive?: boolean },
        ): Promise<void>;
        run(command: string, opts?: { trim?: boolean }): Promise<string>;
        shell(): Promise<SshChannelHandle>;
        spawnDetached(
            command: string,
            opts?: { stderr?: string; stdout?: string },
        ): Promise<void>;
        stat(
            path: string,
        ): Promise<
            {
                isDirectory: boolean;
                isSymlink: boolean;
                mode: number;
                mtime: number;
                size: number;
            },
        >;
        subsystem(name: string): Promise<SshChannelHandle>;
        test(command: string): Promise<boolean>;
        which(name: string): Promise<string | null>;
        writeTextFile(
            path: string,
            content: string,
            opts?: { append?: boolean },
        ): Promise<void>;
    }

    Hierarchy

    • AsyncDisposable
      • SshSession
    Index
    [asyncDispose] chmod close df exec execStream exists forwardOut mkdirp readTextFile rekey rm run shell spawnDetached stat subsystem test which writeTextFile

    • Returns PromiseLike<void>

    • Changes permission bits on one or more paths (chmod). A numeric mode is rendered as octal; a string mode (e.g. 'u+x') is passed through. Paths follow --.

      Parameters

      • path: string | string[]

        A path or array of paths.

      • mode: string | number

        Numeric mode (rendered octal) or a symbolic/string mode.

      • Optionalopts: { recursive?: boolean }

        recursive adds -R.

      Returns Promise<void>

      Nothing on success.

      If chmod exits nonzero.

      1.0.2

      await ssh.chmod('/srv/app/run.sh', 0o755);

    • Closes the session and underlying transport.

      Returns Promise<void>

    • Reports filesystem usage via df -Pk (POSIX 1K-block columns).

      Parameters

      • Optionalpath: string

        Optional path to limit the report to its filesystem.

      Returns Promise<
          {
              availKb: number;
              filesystem: string;
              mountedOn: string;
              sizeKb: number;
              usedKb: number;
              usePercent: number;
          }[],
      >

      One row per filesystem with sizes in kibibytes and the use percentage.

      If df exits nonzero.

      1.0.2

    • Runs a command and resolves with its captured output and exit code.

      Parameters

      • command: string

      Returns Promise<ExecResult>

    • Runs a command on a fresh session channel and returns the live duplex handle without waiting for it to finish, so you can stream write() to its stdin, read stdout/ stderr as they arrive, and await its exit. Use this when you need to interact with the command (feed it stdin, react to partial output) rather than just collect a final result - exec is the collect-to-completion shortcut over this.

      Parameters

      • command: string

        The command line to run (interpreted by the remote login shell).

      Returns Promise<SshChannelHandle>

      The live channel handle.

      If the channel cannot be opened.

      If the server rejects the exec request.

      1.0.2

      await using ssh = await connect({ hostname: 'h', username: 'u', password: 'p' });
      await using ch = await ssh.execStream('cat'); // echoes stdin back on stdout
      await ch.write(new TextEncoder().encode('hello\n'));
      await ch.eof();
      const reader = ch.stdout.getReader();
      const { value } = await reader.read();
      console.log(new TextDecoder().decode(value)); // "hello"
      await ch.exit;

    • Reports whether a filesystem path exists (runs test -e on the quoted path).

      Parameters

      • path: string

        The path to check.

      Returns Promise<boolean>

      true if the path exists, else false.

      1.0.2

    • Opens a direct-tcpip tunnel: the server connects to host:port on your behalf and pipes the bytes back over a duplex channel (the -L-style reach-through). Use it to reach a service - a database, an internal API - that sits behind an SSH bastion.

      Parameters

      • host: string

        The target host the server should connect to.

      • port: number

        The target port.

      Returns Promise<SshChannelHandle>

      A duplex channel: stdout is inbound bytes, write() sends outbound.

      If the server refuses the forward (e.g. policy/host unreachable).

      1.0.0

      await using ssh = await connect({ hostname: 'bastion', username: 'u', password: p });
      await using pg = await ssh.forwardOut('10.0.0.5', 5432); // reach internal Postgres
      await pg.write(startupPacket);
      for await (const chunk of pg.stdout) handle(chunk);

    • Creates a directory and any missing parents (mkdir -p).

      Parameters

      • path: string

        The directory to create.

      • Optionalopts: { mode?: number }

        mode sets the octal permission bits (passed as mkdir -m).

      Returns Promise<void>

      Nothing on success.

      If mkdir exits nonzero.

      1.0.2

      await ssh.mkdirp('/srv/app/releases', { mode: 0o755 });

    • Reads a text file (cat) and returns its contents undecorated (no trimming).

      Parameters

      • path: string

        The file to read.

      Returns Promise<string>

      The file's contents decoded as UTF-8.

      If cat exits nonzero (e.g. the file does not exist).

      1.0.2

    • Forces a key re-exchange now; resolves when new keys are installed.

      Returns Promise<void>

    • Removes one or more paths (rm). Each target is checked by an internal guard that refuses empty, /, ~, ., and .., then the paths are passed after -- so a leading-dash name cannot be read as a flag.

      Parameters

      • path: string | string[]

        A path or array of paths to remove.

      • Optionalopts: { force?: boolean; recursive?: boolean }

        recursive adds -r; force adds -f.

      Returns Promise<void>

      Nothing on success.

      If any target is a refused dangerous path, or rm exits nonzero.

      1.0.2

      await ssh.rm('/tmp/build', { recursive: true, force: true });

    • Runs a command, decodes its stdout as UTF-8, and returns it. Throws when the command exits nonzero, putting the exit code and the decoded stderr in the error message.

      The command is interpreted by the remote login shell, so quote/escape it yourself if it interpolates untrusted values (the typed helpers like mkdirp do this for you via single-quote wrapping).

      The typed helpers (mkdirp/rm/chmod/stat/df/ which/readTextFile/writeTextFile/spawnDetached) assume a POSIX shell, so they work against Linux, macOS, and other Unix remotes (stat and spawnDetached handle the GNU/BSD differences). For a Windows (cmd.exe/PowerShell) or other non-POSIX remote, use run/exec/execStream directly with native commands.

      Parameters

      • command: string

        The command line to run.

      • Optionalopts: { trim?: boolean }

        trim strips leading/trailing whitespace from stdout (default true).

      Returns Promise<string>

      The command's decoded stdout.

      If the command exits with a nonzero code.

      1.0.2

      await using ssh = await connect({ hostname: 'h', username: 'u', password: 'p' });
      const host = await ssh.run('hostname');

    • Launches a command detached so it outlives the SSH channel, with stdin closed and stdout/stderr redirected (default /dev/null). Uses nohup (POSIX; works on Linux and macOS, unlike the Linux-only setsid). Returns once the launcher returns; it does not wait for the spawned process.

      Parameters

      • command: string

        The command to run in the background.

      • Optionalopts: { stderr?: string; stdout?: string }

        stdout/stderr redirect targets (default /dev/null).

      Returns Promise<void>

      Nothing once the process is launched.

      If the launcher exits nonzero.

      1.0.2

      await ssh.spawnDetached('/srv/app/worker', { stdout: '/var/log/worker.log' });

    • Stats a single path. Portable across GNU (Linux) stat -c and BSD (macOS) stat -f: it tries the GNU form and falls back to the BSD form, then normalizes both.

      Parameters

      • path: string

        The path to stat.

      Returns Promise<
          {
              isDirectory: boolean;
              isSymlink: boolean;
              mode: number;
              mtime: number;
              size: number;
          },
      >

      Size in bytes, numeric mode (the full st_mode), mtime in epoch seconds, and isDirectory/isSymlink flags.

      If stat exits nonzero (e.g. the path does not exist).

      1.0.2

    • Runs a command and reports whether it succeeded (exit code 0). Never throws on a nonzero exit - that maps to false - so it reads cleanly as a predicate.

      Parameters

      • command: string

        The command line to run.

      Returns Promise<boolean>

      true if the command exited 0, else false.

      1.0.2

      if (await ssh.test('command -v docker')) console.log('docker present');

    • Resolves the path of an executable on the remote PATH (command -v).

      Parameters

      • name: string

        The command/executable name to look up.

      Returns Promise<string | null>

      The resolved path, or null if not found.

      1.0.2

    • Writes text to a file by streaming the bytes to cat's stdin, so the payload is never shell-quoted. Truncates by default; append appends instead (cat >>).

      Parameters

      • path: string

        The file to write.

      • content: string

        The text to write (UTF-8 encoded onto stdin).

      • Optionalopts: { append?: boolean }

        append appends rather than truncating.

      Returns Promise<void>

      Nothing on success.

      If the write command exits nonzero.

      1.0.2

      await ssh.writeTextFile('/srv/app/.env', 'PORT=8080\n');

    Settings
    Member Visibility

    On This Page
    Methods