gsudo Documentation

C# command-line & elevate repository by @gerardog. Desktop release binaries & installers with 6.1k stars.

6,065 stars C# C# 24 files · ~18,466 tokens #command-line#elevate#elevated-commands#elevated-permissions#powershell#runas#sudo#sudo-for-windows
RAW Doc

Technical Documentation: gerardog/gsudo

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`)

gsudo - a sudo for Windows




gsudo is a sudo equivalent for Windows, with a similar user-experience as the original Unix/Linux sudo.
Allows you to run a command (or re-launch your current shell) with elevated permissions, in the current console window or a new one.

Just prepend gsudo (or the sudo alias) to your command and it will run elevated. For PowerShell use this syntax: gsudo { ScriptBlock }

One UAC popup will appear each time. You can see less popups if you enable gsudo cache.

It detects your current shell and elevates your command as native shell commands. (Supports Cmd, PowerShell, WSL, git-bash, MinGW, Cygwin, Yori, Take Command, BusyBox & NuShell.)

Table of contents

⭐ Extended documentation available at: https://gerardog.github.io/gsudo/

Demo

(with gsudo config CacheMode auto)

Features

  • Elevated commands are shown in the current console. No new window (unless you specify -n)

  • Credentials cache: gsudo can elevate many times showing only one UAC pop-up if the user opts-in to enable the cache.

  • Detects your current shell (Supports CMD, PowerShell, WSL, Bash for Windows (Git-Bash/MinGW/MSYS2/Cygwin), Yori, Take Command and NuShell), and elevates your command correctly.

  • Supports being used on scripts:

    • Outputs StdOut/StdErr can be piped or captured (e.g. gsudo dir | findstr /c:"bytes free" > FreeSpace.txt) and exit codes too (%errorlevel%). If gsudo fails to elevate, the exit code will be 999.
    • If gsudo is invoked from an already elevated console, it will just run the command (it won't fail). So, you don't have to worry if you run gsudo or a script that uses gsudo from an already elevated console. (The UAC popup will not appear, as no elevation is required)

  • gsudo !! elevates the last executed command. Works on CMD, Git-Bash, MinGW, Cygwin (and PowerShell with gsudo module only)

Installation

  • Using Scoop: scoop install gsudo
  • Using WinGet: winget install gerardog.gsudo
  • Using Chocolatey: choco install gsudo
  • Manual Setup: download and run the proper MSI installer for you system from the latest release.
  • Running this line: (script):
    powershell
    PowerShell -Command "Set-ExecutionPolicy RemoteSigned -scope Process; [Net.ServicePointManager]::SecurityProtocol = 'Tls12'; iwr -useb https://raw.githubusercontent.com/gerardog/gsudo/master/installgsudo.ps1 | iex"
  • Portable:
    1. Download gsudo.portable.zip from the latest release.
    2. Extract the folder corresponding to your processor architecture (x64, x86, or arm64) from the zip file to a suitable directory on your computer.
    3. Optionally, add that directory to your system's PATH environment variable if it's not already accessible.

Please restart all your console windows after installing to ensure that the PATH environment variable is refreshed.

Note: gsudo.exe is portable. No windows service is required or system change is done, except adding it to the Path.

Usage

powershell
gsudo [options]                  # Starts your current shell elevated
gsudo [options] {command} [args] # Runs {command} with elevated permissions
gsudo cache [on | off | help]    # Starts/Stops a credentials cache session. (less UAC popups)
gsudo status [--json | filter ]  # Shows current user, cache and console status.
gsudo !!                         # Re-run last command as admin. (YMMV)
text
/* Detailed source-code truncated for AI context efficiency. */

Note: You can use anywhere the sudo alias created by the installers.

Examples:

powershell
gsudo   # elevates the current shell in the current console window (Supports Cmd/PowerShell/Pwsh Core/Yori/Take Command/git-bash/cygwin)
gsudo -n # launch the current shell elevated in a new console window
gsudo -n -w powershell ./Do-Something.ps1 # launch in new window and wait for exit
gsudo notepad %windir%\system32\drivers\etc\hosts # launch windows app

sudo notepad # sudo alias built-in

# redirect/pipe input/output/error example
gsudo dir | findstr /c:"bytes free" > FreeSpace.txt

gsudo config LogLevel "Error"          # Configure Reduced logging
gsudo config Prompt "$P [elevated]$G " # Configure a custom Elevated Prompt
gsudo config Prompt --reset            # Reset to default value

# Enable credentials cache (less UAC popups):
gsudo config CacheMode Auto

Usage from PowerShell / PowerShell Core

gsudo detects if invoked from PowerShell and elevates PS commands (unless -d is used to elevate CMD commands).

The command to elevate will run in a different process, so it can't access the parent $variables and scope.

To elevate a commands or script block: Wrap it in {curly braces}.

powershell
# Syntax:
gsudo { ScriptBlock }
gsudo [options] { ScriptBlock } [-args $argument1[..., $argumentN]] ;

# Examples:
gsudo { Write-Output "Hello World" }

# Pass arguments with -args
$MyString = "Hello World"
gsudo { Write-Output $args[0] } -args $MyString

# Output is serialized as PSObjects with properties.
$services = gsudo { Get-Service 'WSearch', 'Winmgmt'}
Write-Output $services.DisplayName

# Inputs too: Example elevated iteration of a list.
Get-ChildItem . | gsudo { $Input.CreationTime}

Alternative syntaxes:

  1. Invoke-gsudo wrapper function: (much slower)
powershell
# Pass values (not variables by reference) by prefixing `$using:`. I.E.

$MyString = "Hello World"
Invoke-Gsudo { Write-Output $using:MyString }

# Syntax:
Invoke-Gsudo [-ScriptBlock] <ScriptBlock>
             [[-ArgumentList] <Object[]>]
             [-InputObject <PSObject>]
             [-LoadProfile | -NoProfile]
             [-Credential <PSCredential>]
text
- PowerShell function.
- Performs auto serialization of inputs & outputs.
- You can prefix variables with the `$using:` scope modifier (like `$using:variableName`) and their serialized value is applied.
- Use `-LoadProfile` or `-NoProfile` to override profile loading or not.
- Use `-Credential` option for Run As User (same as `-u` but for `Get-Credentials`).
- Better forwarding of your current context to the elevated instance (current Location, $ErrorActionPreference)
  1. Manual string interpolation. (not recommended)
    I don't recommend this approach as it is really hard to do proper escape all special characters.
powershell
Usage: gsudo 'string literal'

# Variable substitutions example:
$file='C:\My Secret.txt';
$algorithm='md5';
$hash = gsudo "(Get-FileHash '$file' -Algorithm $algorithm).Hash"
# or
$hash = gsudo "(Get-FileHash ""$file"" -Algorithm $algorithm).Hash"
  • Accepts a string literal with the command to elevate.
  • Returns a list of strings.

PowerShell Module

  • Optional: Import module gsudoModule.psd1 into your PowerShell Profile:

    • Adds syntax auto-complete to gsudo in PowerShell. Plus, it suggests the 3 previous commands, making your workflow smoother than ever!
    • Enables gsudo !! on Powershell, to elevate the last executed command.
    • Adds Functions:
      • Test-IsGsudoCacheAvailable Returns true if a gsudo cache is active (meaning elevation with no UAC is possible).
      • Test-IsProcessElevated: Returns true if the current process is elevated.
      • Test-IsAdminMember: Returns true if the current user is member of the Local Administrators groups, which means it can elevate with.
    powershell
    # Add the following line to your $PROFILE
Import-Module "gsudoModule"

# Or run:
Write-Output "`nImport-Module `"gsudoModule`"" | Add-Content $PROFILE
    • If you haven't already customized your PowerShell prompt (for example by installing Oh-My-Posh), you can easily add a red # indicating that the current process is elevated:

    To do so add this line to your profile (after importing gsudoModule):

    powershell
    Set-Alias Prompt gsudoPrompt

Usage from WSL (Windows Subsystem for Linux)

On WSL, elevation and root are different concepts. root allows full administration of WSL but not the windows system. Use WSL's native su or sudo to gain root access. To get admin privilege on the Windows box you need to elevate the WSL.EXE process. gsudo allows that (a UAC popup will appear).

On WSL bash, prepend gsudo to elevate WSL commands or gsudo -d for CMD commands.

bash
# elevate default shell
PC:~$ gsudo

# run elevated WSL command
PC:~$ gsudo mkdir /mnt/c/Windows/MyFolder

# run elevated Windows command
PC:~$ gsudo -d notepad C:/Windows/System32/drivers/etc/hosts
PC:~$ gsudo -d "notepad C:\Windows\System32\drivers\etc\hosts"

# test for gsudo and command success
retval=$?;
if [ $retval -eq 0 ]; then
    echo "Success";
elif [ $retval -eq $((999 % 256)) ]; then # gsudo failure exit code (999) is read as 231 on wsl (999 mod 256)
    echo "gsudo failed to elevate!";
else
    echo "Command failed with exit code $retval";
fi;

Configuration

powershell
gsudo config                          # Show current config settings & values.
 gsudo config {key} [--global] [value] # Read or write a user setting
 gsudo config {key} [--global] --reset # Reset config to default value
 --global                              # Affects all users (overrides user settings)

Credentials Cache

The Credentials Cache, if enabled and active, allows to elevate several times from a parent process with only one UAC pop-up. After 5 minutes without elevations, the cache session closes automatically (Configurable timeout via gsudo config CacheDuration).

While this very convenient, it's important to understand its potential security risks. Even if gsudo itself is secure, the inherent vulnerability lies in the host process. If your system is already compromised by a malicious process, it can manipulate the permitted process (e.g., Cmd/Powershell) and force an active gsudo cache instance to elevate privileges without triggering a UAC prompt.

This risk is the trade-off for using the Credentials Cache. The cache is safe to use as long as you are confident there are no malicious processes running on your system.

Here are the Credentials Cache Modes:

  • Explicit: (default) Every elevation shows a UAC popup, unless a cache session is started manually...
    • To start or stop a cache session run: gsudo cache {on | off}
    • This is the default mode. (Use gsudo config CacheMode Explicit to revert to this value).
  • Auto: Similar to unix-sudo. The first elevation shows a UAC popup and starts a cache session automatically.
    • Run gsudo config CacheMode Auto to use this mode.
  • Disabled: Every elevation shows a UAC popup, and trying to start a cache session will throw an error..
    • Run gsudo config CacheMode Disabled to use this mode.

In any case, you can stop all cache sessions with gsudo -k.

Learn more

Known issues

  • The elevated instances do not have access to the network shares connected on the non-elevated space. This is not a gsudo issue but how Windows works. Use --copyNS to replicate Network Shares into the elevated session, but this is not bi-directional and is interactive (may prompt for user/password).

  • gsudo.exe can be placed on a network share and invoked as \\server\share\gsudo {command} but doesn't work if your current folder is a network drive. For example do not map \\server\share\ to Z: and then Z:\>gsudo do-something.

  • Please report issues in the Issues section.

FAQ

  • Why is it named gsudo instead of just sudo?

    When I created gsudo, there were other sudo packages on most Windows popular package managers such as Chocolatey and Scoop, so I had no other choice to pick another name. gsudo installers create an alias for sudo, so feel free to use sudo on your command line to invoke gsudo.

  • Which dotnet version is built with?

    Versions prior to v1.3.0 used .NET 4.6 because it was included in every Windows 10/11 installation.

    From v1.4.0 up to v2.5.1, gsudo has been built using .net7.0 NativeAOT. This approach offers faster load times, reduced memory usage, and allows the tool to run on machines without any .NET runtime installed.

    Starting with v2.6.0, we've migrated to net9.0 due to the end-of-life of net7.0.

  • Is gsudo a port of *nix sudo?

    No. gsudo reminds of the original sudo regarding user expectations. Many sudo features are *nix specific and could never have a Windows counterpart. Other features (such as sudoers) could potentially be implemented but are not at this point.

  • What are the requirements? Does it work in Windows 7/8?

    It works on Win7 SP1 onwards. Some features may only work in Windows 10/11, like elevating as TrustedInstaller.

  • How do I return to the previous security level after using gsudo?

    In the same way as you would with Unix/Linux sudo: gsudo does not alter the current process, instead it launches a new process with different permissions/integrity level. To go back to the previous level, just end the new process. For Command Prompt or PowerShell just type exit.

Please support gsudo! 💵

  • Please give us a star! ⭐
  • Help spread the word by mentioning gsudo in social networks!
  • Sponsor or Donate

Overview (`docs/README.md`)

Website

This is the source code of gsudo documentation website.

The documentation is available at: https://gerardog.github.io/gsudo/

This website is built using Docusaurus 2, a modern static website generator.

Website Installation

text
$ yarn

Local Development

text
$ yarn start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

Build

text
$ yarn build

This command generates static content into the build directory and can be served using any static contents hosting service.

Overview (`sample-scripts/readme.md`)

gsudo Sample Scripts

This folder contains sample scripts demonstrating how to use gsudo to elevate privileges on a Windows machine. The provided scripts include:

  1. Script Self-Elevation: A technique to ensure that the current script is running elevated, by detecting when it is not, and elevating itself. More details can be found in the gsudo documentation on script self-elevation.

  2. Many Elevations Using gsudo Cache:

  3. Don't show an UAC pop-up: Perform an elevated admin task if and only if it can be done without an interactive UAC pop-up. (i.e. when already elevated or gsudo cache is active)

These scripts are examples and should be used with caution. Always review and understand the code you are executing on your system.

Overview (`build/Chocolatey/ReadMe.md`)

Summary

How do I create packages? See https://chocolatey.org/docs/create-packages

If you are submitting packages to the community feed (https://chocolatey.org)
always try to ensure you have read, understood and adhere to the create
packages wiki link above.

Automatic Packaging Updates?

Consider making this package an automatic package, for the best
maintainability over time. Read up at https://chocolatey.org/docs/automatic-packages

Shim Generation

Any executables you include in the package or download (but don't call
install against using the built-in functions) will be automatically shimmed.

This means those executables will automatically be included on the path.
Shim generation runs whether the package is self-contained or uses automation
scripts.

By default, these are considered console applications.

If the application is a GUI, you should create an empty file next to the exe
named 'name.exe.gui' e.g. 'bob.exe' would need a file named 'bob.exe.gui'.
See https://chocolatey.org/docs/create-packages#how-do-i-set-up-shims-for-applications-that-have-a-gui

If you want to ignore the executable, create an empty file next to the exe
named 'name.exe.ignore' e.g. 'bob.exe' would need a file named
'bob.exe.ignore'.
See https://chocolatey.org/docs/create-packages#how-do-i-exclude-executables-from-getting-shims

Self-Contained?

If you have a self-contained package, you can remove the automation scripts
entirely and just include the executables, they will automatically get shimmed,
which puts them on the path. Ensure you have the legal right to distribute
the application though. See https://chocolatey.org/docs/legal.

You should read up on the Shim Generation section to familiarize yourself
on what to do with GUI applications and/or ignoring shims.

Automation Scripts

You have a powerful use of Chocolatey, as you are using PowerShell. So you
can do just about anything you need. Choco has some very handy built-in
functions that you can use, these are sometimes called the helpers.

Built-In Functions

https://chocolatey.org/docs/helpers-reference

A note about a couple:

Getting package specific information

Use the package parameters pattern - see https://chocolatey.org/docs/how-to-parse-package-parameters-argument

Need to mount an ISO?

https://chocolatey.org/docs/how-to-mount-an-iso-in-chocolatey-package

Environment Variables

Chocolatey makes a number of environment variables available (You can access any of these with $env:TheVariableNameBelow):

  • TEMP = Overridden to the CacheLocation, but may be the same as the original TEMP folder
  • ChocolateyInstall = Top level folder where Chocolatey is installed
  • chocolateyPackageName = The name of the package, equivalent to the id in the nuspec (0.9.9+)
  • chocolateyPackageVersion = The version of the package, equivalent to the version in the nuspec (0.9.9+)
  • chocolateyPackageFolder = The top level location of the package folder

Advanced Environment Variables

The following are more advanced settings:

  • chocolateyPackageParameters = (0.9.8.22+)
  • CHOCOLATEY_VERSION = The version of Choco you normally see. Use if you are 'lighting' things up based on choco version. (0.9.9+)
    • Otherwise take a dependency on the specific version you need.
  • chocolateyForceX86 = If available and set to 'true', then user has requested 32bit version. (0.9.9+)
    • Automatically handled in built in Choco functions.
  • OS_PLATFORM = Like Windows, OSX, Linux. (0.9.9+)
  • OS_VERSION = The version of OS, like 6.1 something something for Windows. (0.9.9+)
  • OS_NAME = The reported name of the OS. (0.9.9+)
  • IS_PROCESSELEVATED = Is the process elevated? (0.9.9+)

Experimental Environment Variables

The following are experimental or use not recommended:

  • OS_IS64BIT = This may not return correctly - it may depend on the process the app is running under (0.9.9+)
  • CHOCOLATEY_VERSION_PRODUCT = the version of Choco that may match CHOCOLATEY_VERSION but may be different (0.9.9+)
    • it's based on git describe
  • IS_ADMIN = Is the user an administrator? But doesn't tell you if the process is elevated. (0.9.9+)
  • chocolateyInstallOverride = Not for use in package automation scripts. (0.9.9+)
  • chocolateyInstallArguments = the installer arguments meant for the native installer. You should use chocolateyPackageParameters instead. (0.9.9+)

Docs Intro (`docs/docs/intro.md`)

Introduction

gsudo is a sudo equivalent for Windows, with a similar user-experience as the original *nix sudo.

It allows to run commands with elevated permissions, or to elevate the current shell, in the current console window or a new one.

Just prepend gsudo (or the sudo alias) to your command and it will run elevated. One UAC popup will appear each time. You can see less popups if you enable gsudo cache.

It is designed so it is easy to install, easy to use, and feels familiar with other popular tools.

:::info
gsudo allows you to easily cherry-pick which commands to elevate, and save time by not switching context between elevated and non-elevated windows.
:::

Features

  • It is a proper sudo for windows:

    • Executes the desired command with elevated permissions (or as another user).
    • Elevated commands are shown in the current user-level console. No new window. (Unless you specify -n)
    • Full console support: Colors, full keyboard, auto-completion, etc.
    • Supports I/O redirection.
    • Handles Ctrl-C properly
    • Supports worldwide encodings & codepages

  • Uses the current shell to interpret the command to elevate:

  • If no command is specified, it starts an elevated shell.

  • Credentials cache: gsudo can elevate many times showing only one UAC pop-up if the user opts-in to enable the cache.

  • Supports being used on scripts:

    • Returns the command exit code (%errorlevel%). If gsudo fails to elevate, the exit code will be 999.
    • If gsudo is invoked from an already elevated console, it will run the command as-is (won't throw error). So, don't worry if you run gsudo or a script that uses gsudo when already elevated. (No elevation is required, no UAC popup)

  • Use gsudo !! to elevate the last ran command. Works on CMD, Git-Bash, MinGW, MSYS2, Cygwin (and PowerShell with gsudo module only)

Read How to Use for your favorite shell to see additional features.

Demo

Blog 2022 08 21 Dotnet7 Index (`docs/blog/2022-08-21-dotnet7/index.md`)

slug: gsudo-dotnet-7 title: Migrating gsudo to .NET 7 authors: [gerardog] tags: []

The first gsudo versions were made in 2019, around the release of .NET Core 3. I tried to figure out how .NET Core's redistribution model worked, but it didn't worked for me. One should either redistribute the full runtime, or ask the user to manually download and install it. There was another option: to build a self-contained app (with runtime embedded) but that increased the output size by more than 80mb!

The alternative was to target .NET Framework v4.6. This version is bundled with every Windows 10/11. When targeting it, gsudo build output size was around 100kb. The app on v4.6 loaded faster, so targeting v4.6 seemed logical. It was small, fast, and the installation didn't required any big runtime redistribution or additional steps.

Recently, things have changed a little with .NET 7 Preview 3 announcement and NativeAOT: "Publishing your app as native AOT produces an app that is self-contained and that has been ahead-of-time (AOT) compiled to native code. Native AOT apps start up very quickly and use less memory. Users of the application can run it on a machine that doesn't have the .NET runtime installed."

I'm almost sold! Let's try it out... (sounds of frenetic typing)... Ok, that was 18 files changed. Now I have a multi-target project that can compile for v4.6 or v7. Not bad.

But not everyone's cup of tea: NativeAOT builds for each specific platform, so instead of having one AnyCPU build, now I have two (x64 and x86). But also, NativeAOT is only supported on x64. The closest for x86 is a self-contained build with Ready2Run.

Let's do some test the performance. So first let´s build for each platform:

powershell
# Build .NET Framework v4.6
msbuild /t:Restore /p:RestorePackagesConfig=true src\gsudo.sln /v:Minimal /p:TargetFrameworkVersion=v4.6
msbuild /t:Rebuild /p:Configuration=Release src\gsudo\gsudo.csproj /v:Minimal /p:WarningLevel=0 /p:TargetFrameworkVersion=v4.6
# Build .NET 7.0 x64 build with NativeAOT
dotnet clean .\src\gsudo\gsudo.csproj -f net7.0 | Out-null
dotnet publish .\src\gsudo\gsudo.csproj -c Release -f net7.0 -r win-x64 --sc -p:PublishAot=true -p:IlcOptimizationPreference=Size -v minimal -p:WarningLevel=0
# Build .NET 7.0 x86 build with Ready2Run
dotnet clean .\src\gsudo\gsudo.csproj -f net7.0 -r win-x86 | Out-null
dotnet publish .\src\gsudo\gsudo.csproj -c Release -f net7.0 -r win-x86 --sc -p:PublishReadyToRun=true -p:PublishSingleFile=true -v minimal -p:WarningLevel=0

Now let´s meassure 100 elevations using a preexisting credentials cache. I am using gsudo -d to force an elevation using cmd.exe, which loads much faster and predictable than Powershell. Then I repeated the tests with each different build.

powershell
$gsudo="C:\git\gsudo\src\gsudo\bin\net46\gsudo.exe"
& $gsudo cache on | out-null 	# start a cache session.
& $gsudo -d dir | out-null		# test the cache session.
Measure-Command { 1..100 | % { & $gsudo -d dir} } | select -Property TotalSeconds | Format-List
& $gsudo -k | out-null 			# close cache.

The first results were absurd. I found out Windows Defender takes extra time to verify unsigned apps in the cloud. So I disabled Defender and started over.

v1.3.0 (Net 4.6 + ilmerge + CodeSigned) Latest (Net 4.6 unsigned) Net 7.0 x64 NativeAOT (unsigned) Net 7.0 x86 Ready2Run (unsigned)
Size 180.5 KB 208.5 KB 6.17 MB 16.89 MB
Time to elevate 100 times (sum) 12.75 s 12.62 s 7.83 s 10.94 s
Performance improvement (baseline) 1.04% 38.62% 14.18%

Wow! An improvement of 38.62% is significant enough to ignore the fact that the file size has increased 6 MB, or almost 30 times.

Should gsudo target .NET 7.0?

The problem is that the installer should provide for all platforms, and so far I´ve only focused on x64. What options do I have?

  • I could fall back to Net 4.6 (targeting AnyCPU) for the remaining platforms. The down-side would be different prerequisites for each scenario. But the installer would only grow 6mb.
  • Or include x86 Net 7.0 Read2Run version. It´s faster, but takes 16mb. The setup including both would take 23 MB (actually 10mb when compressed)!

Current situation

Right now my code-signing certificate is expired. Once I´ve got a new certificate, I will be making a test release. I will update this post then.

Blog Authors.Yml (`docs/blog/authors.yml`)

gerardog:
name: Gerardo Grignoli

title: gsudo Creator

url: https://github.com/gerardog
image_url: https://avatars.githubusercontent.com/u/3901474?s=96&v=4

Docs Credentials Cache (`docs/docs/credentials-cache.md`)

Introduction

The Credentials Cache is an optional feature that allows to elevate several times from a parent process with only one UAC pop-up.

An active credentials cache session is just an elevated instance of gsudo that stays running and allows the invoker process to elevate again. No windows service or setup involved.

It is convenient, but it's safe only if you are not already hosting a malicious process: No matter how secure gsudo itself is, a malicious process could trick the allowed process (Cmd/Powershell) and force a running gsudo cache instance to elevate silently.

Cache Modes

The cache mode can be set with gsudo config CacheMode auto|explicit|disabled

  • Explicit: (default) Every elevation shows a UAC popup, unless a cache session is started explicitly with gsudo cache on.
powershell
gsudo config CacheMode Explicit # This is optional since Explicit is the default.

gsudo command1 # 1st UAC Popup shown
gsudo command2 # 2nd UAC Popup shown
gsudo cache on # 3rd UAC Popup shown, cache session started
gsudo command3 # Elevation without popup 
gsudo command4 # Elevation without popup 
gsudo cache off # (or gsudo -k) Ends the cache session. Next elevation will show a UAC popup.
  • Auto: Simil-unix-sudo. The first elevation shows a UAC Popup and starts a cache session automatically.
powershell
gsudo config CacheMode Auto # Only need to run once, this setting is persistent.

gsudo command1 # 1st UAC Popup shown, cache session started
gsudo command2 # Elevation without popup
gsudo command3 # Elevation without popup 
gsudo cache off # (or gsudo -k) Ends the cache session. Next elevation will show a UAC popup.
  • Disabled: Every elevation request shows a UAC popup. Attempts to start a Cache Session throws error.

Use gsudo cache on|off to start/stop a cache session manually (i.e. allow/disallow elevation of the current process with no additional UAC popups).

Use gsudo -k to terminate all cache sessions. (Use this before leaving your computer unattended to someone else.)

The cache session ends automatically when the allowed process ends or if no elevations requests are received for 5 minutes (configurable via gsudo config CacheDuration).

Usage

  • gsudo cache [-h] Shows cache help

  • gsudo cache {on | off} [-p {pid}] [-d {time}] Start/stop a gsudo cache session.

    • -p | --pid {pid} Specify which process can use the cache. (Use 0 for any, Default=caller pid)
    • -d | --duration {hh:mm:ss} Max time the cache can stay idle before closing.
      • Use '-1' to keep open until logoff (or until cache off, or -k).
      • The default is CacheDuration is 5 minutes.

Docs Gsudo Vs Sudo (`docs/docs/gsudo-vs-sudo.md`)

Comparison between gsudo and Microsoft sudo

gsudo was born in 2019 as a productivity tool and is open-source. It has been downloaded over 700k times so far and has enjoyed a warm reception from users. It is very easy to install and works from Windows 7 SP1 up to Windows 11.

Microsoft initially declined to create a similar tool, citing security concerns. However gsudo's documentation challenged this view arguing that absolute security is unattainable without altering Windows itself, and that the default same-desktop UAC is not completely secure either.

In February 2024, Microsoft reversed its stance and released Sudo for Windows.

Surprisingly, Microsoft's sudo does not leverage new OS features to enhance security. Its mechanisms are akin to gsudo, making their security models comparable. The question of which one is more secure depends on which version of each are you comparing, and how many open bugs it has. The initial release of Microsoft's sudo presented some critical issues that they will hopefully address very soon. gsudo has fixed similar issues in the past and may in the future.

Sudo Tools Feature Comparison

Is it a proper Sudo tool?

Feature gsudo Sudo for Windows
Executes command with elevated permissions Yes Yes
Supports output redirection (sudo dir > file.txt) Yes Yes
Supports input redirection (echo md SomeFolder | sudo cmd) Yes Yes
Returns the command exit code Yes Yes
Preserves the current directory Yes Yes, except in new-window mode! ⚠️ Learn More
Source code available Yes Yes
Works with Win11 Administration Protection Yes No

Security Impersonation Features

Feature gsudo Sudo for Windows
Run with custom Integrity Yes (-i, --integrity) No
Run as System Yes (-s, --system) No
Run as TrustedInstaller Yes (--ti) No
Run as user Yes (-u user) No

User Experience

Feature gsudo Sudo for Windows
Easy to install and update Yes (winget, choco, scoop) No (Windows Insider build required)
See less UAC Pop-ups Yes (Credentials Cache) No
Elevate current shell Yes No
Elevate commands using current shell Yes No
Red # indicator for elevation on CMD Yes No

Additional Features

Feature gsudo Sudo for Windows
Run in new window Yes Yes
Option to keep new window open until a key is pressed Yes No
Option to keep new window's shell open Yes No
Run with Input Disabled Yes Yes
Elevate last command with sudo !! Yes No

PowerShell

Feature gsudo Sudo for Windows
Elevation syntax gsudo { scriptblock } -args $a,$b syntax sudo pwsh { scriptblock } -args $a,$b (Unofficial!)
Auto-complete of last 3 commands Yes (with gsudoModule) No
Auto-complete of command line arguments Yes (with gsudoModule) No
Red # indicator for elevation Yes (with gsudoModule) No

What if I install both?

If you have both Microsoft Sudo and gsudo installed, they both should work independently.

The sudo keyword will run Microsoft's sudo instead of gsudo because the typical install of Sudo for Windows puts it in c:\Windows\System32\sudo.exe. This folder appears first in the PATH environment variable, therefore when running sudo, the Microsoft sudo.exe will take precedence over gsudo's sudo alias.

To change this behavior and make sudo point to gsudo you can
call gsudo config PathPrecedence true and restart all your consoles to apply the change. Setting it back to false will revert to the normal behavior.

Additionally, gsudo now supports Microsoft sudo styled arguments such as --inline, --disable-input, --preserve-env, --new-window, and -D / --chdir {directory}, ensuring a smoother transition for users familiar with Microsoft sudo.

Docs How It Works (`docs/docs/how-it-works.md`)

How does it work internally?

When gsudo is invoked, an elevated instance of gsudo in service mode is launched (with Verb='RunAs'). The service will allow one elevation (or many if the credentials cache is enabled).

Elevation modes

To achieve the sudo functionality, gsudo has 4 different mechanisms implemented.

In a way, each one superseded the previous one, leading to the current default TokenSwitch.

In the source code, each mode is implemented as one IProcessRenderer (running non-elevated) and a IProcessHost (running in the elevated service).

Communication between both is done via two Named Pipes in the ProtectedPrefix\Administrators namespace. One for data and another for control. Each elevation mode defines the "communication protocol", what is sent thru each pipe.

These are the elevations modes implemented in gsudo, in the order they were implemented:

Piped mode

This is a naive mechanism, implemented first more like a proof of concept (that later proved to be useful).

The elevated PipedProcessHost runs the command with its I/O redirected (For example as in (input) > Elevated Process > (output)), and sends all I/O to the unelevated via named pipes.

The PipedProcessRenderer captures input and display the output on screen. In this mode, keyboard input is managed by the client console (without knowledge of which app you are running), and not by the elevated command/shell, hence TAB key auto-completion doesn't work. The user experience is far from ideal.

The process is created with the elevated Environment Variables.

Pros:

  • Redirection works

Cons:

  • Apps always run in redirected mode.
  • Input only support of chars, not key presses.
  • Struggles with encoding, especially explicit code page changes.

VT mode (PseudoConsole)

:::info Side story
It was the day Microsoft announced Pseudo Consoles for Windows, I asked myself: What can PseudoConsoles be used for? a sudo for windows!!
:::

The elevated instance runs a VT PseudoConsole, and sends all I/O it to the unelevated via named pipes.

The process is created with the elevated Environment Variables.

Pros:

  • Full featured console screen
  • Full input support.

Cons:

  • Good but not best performance (compared with the following alternatives).
  • Apps always runs in console mode (not redirected). Redirection could be done but the result would be more like console screen recording than process redirection.
  • Struggles with encoding IF encoding or code page changes.
  • Console screen resizing still not implemented.

Attached mode

The elevated window 'attaches' to the non-elevated. The bridge is actually done by Windows and ConHost. Doesn't work with I/O redirected.

The process is created with the elevated Environment Variables.

Pros:

  • Native console functioning. Full speed, colors, input, etc.
  • No encoding issues

Cons:

  • Does not support redirection

TokenSwitch Mode

This is the current default mode. Using undocumented kernel32 Apis, the unelevated instance creates the new process in paused mode, then the elevated host replaces it's primary token, and its execution is resumed.

The process is created with the non-elevated context/Environment Variables.

Pros:

  • Native console functioning. Full speed, colors, input, etc.
  • No encoding issues
  • Supports redirection

Cons:

  • (debatable) The new process inherits the non-elevated environment variables.

This last item is a confirmed problem when the elevation is done as somebody else (i.e. the current user is not admin and RunAs asks for credentials). To avoid it, and only in this scenario, this mode falls back to Attached mode (if no redirection) or Piped mode (if redirection exists).

Should the elevated process inherit the same environment variables?

Great question. If your user is a local admin, i.e. you elevate as yourself, both contexts have similar if not same env vars.

But if you are not local admin, UAC will prompt for credentials, and then you will be running as another user, so env var isolation becomes more important. On Linux/Unix, you always sudo as somebody else and env vars are not preserved, unless -E is specified. gsudo provides --copyEV to copy all the vars, except %USERNAME%.

How do I force one mode over the other?

You shouldn't. gsudo should do a better job choosing than you. Still reading? Ok... I will tell you. But this is marked as deprecated and can change anytime.

To force Attached mode use --attached or permanently with gsudo config ForceAttachedConsole True

To force Piped mode use --piped or permanently with gsudo config ForcePipedConsole True

To force VT mode use --vt or permanently with gsudo config ForceVTConsole True

Use only one at the same time.

Docs Install (`docs/docs/install.md`)

hide_title: true title: How to Install sidebar_position: 2

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

How to Install gsudo

If you use any of the following Package Managers:

  • Using WinGet: Run winget install gerardog.gsudo
  • Using Chocolatey: Run choco install gsudo
  • Using Scoop: Run scoop install gsudo

Or:

  • Download and run the MSI file from the latest release.
  • Or use the following script to achieve the same:
    powershell
    PowerShell -Command "Set-ExecutionPolicy RemoteSigned -scope Process; [Net.ServicePointManager]::SecurityProtocol = 'Tls12'; iwr -useb https://raw.githubusercontent.com/gerardog/gsudo/master/installgsudo.ps1 | iex"
  • Manually: Download the ZIP file from the latest release. Uncompress and add to PATH.
  • Download gsudo.Setup.[platform].msi from the latest release, and run.

:::caution
Please restart your consoles after installing, to refresh the PATH environment variable.
:::

:::info
gsudo is just a portable console app. No Windows service is required or system change is done, except adding gsudo to the PATH.
:::

Configure your Shell

On the following shells you get a better experience if you follow some manual configuration:

Docs Security (`docs/docs/security.md`)

Why doesn't Windows have a `sudo` command? Should it have one?

To answer this question, we first have to take a look back at the history.

In August 2002, Chris Paget released a white paper describing a form of attack against event-driven systems that he termed Shatter Attack. It allowed processes in the same session to bypass security restrictions by abusing Windows Message loop.

Microsoft's response was to add "User Interface Privilege Isolation" (UIPI) and the "User Access Control" (UAC) popup to the next major release: Windows Vista. Privileged processes would then run "elevated" at high integrity level, out of reach of processes at lower, non-admin, levels.

I assume that at this point, Microsoft decided not to make a sudo tool for windows. It would be an unwanted bridge between two worlds that intended to isolate.

However, that insulation quickly proved to be weak. Let me quote Raymond Chen from Microsoft:

There’s a setting that lets you specify how often you want to be prompted by UAC. You can set any of four levels:

  • Always notify
  • Notify only when apps try to change settings, use the secure desktop (Default mode)
  • Notify only when apps try to change settings, don’t use the secure desktop
  • Never notify

Although it looks like there are four settings, in a theoretical sense, there really are only two settings.

  • Always notify
  • Meh

The reason why all the other options collapse into Meh is that the Notify only when apps try to change settings option can be subverted by any app simply by injecting a thread (... a hacking technique explained ...)

And, up to this day, Windows 10 & 11, defaults corresponds to that "Meh". Microsoft's default stance is user convenience at the expense of lesser security.

[Windows 11 UAC Settings: Default mode is recommended only if you don't run untrusted software.]

Over time, more than a hundred UAC-bypass techniques have been disclosed. Many of them still work in an updated Windows 11. It is Windows Defender, or your antivirus of choice, who may stop them (hopefully). But if you disable your AV, UAC bypass is easy.

And Microsoft can't just patch them all without loosing 'convenience' features. They instead, they assumed publicly that UAC/UIPI in default mode is not a security boundary. I will quote Microsoft documentation :

Same-desktop Elevation in UAC isn't a security boundary. It can be hijacked by unprivileged software that runs on the same desktop. Same-desktop Elevation should be considered a convenience feature.

Which to me, it means: UAC is a convenience tool. It does not protect you from threats, it works as a warning that protects you from shooting yourself in the foot.

And if UAC is a convenience tool, in my opinion it's not doing the best possible job:

  • You waste important time by switching between elevated and unelevated windows. You must manually carry your command and context to the elevated window, each time, back and forth.
  • ... or you suffer from "elevation fatigue". For example, you elevate a whole console beforehand, and you do all your stuff there, likely running non-admin or untrusted stuff as admin.

In conclusion:

  • Same-desktop UAC is a vulnerable convenience feature.
  • gsudo is also a vulnerable convenience feature.
  • Whether you use gsudo or not, the only thing that protects you from malware is not UAC, it is you and your Antivirus..

So, if you decide to use gsudo, here are the risks:

What are the risks of running gsudo?

gsudo could be used as an attack vector for escalation of privileges. Using antivirus software and avoiding running untrusted software

  • Abusing an elevation made with gsudo:

    A medium integrity process could drive the gsudo-elevated process.

    When gsudo elevates in the same console, it creates a connection between a medium and a high integrity process. A malicious process (at medium integrity) can then drive the medium integrity console: sending keystrokes to the high integrity app, or scrapping its screen.

    In my opinion, this is a mild risk that you are already exposed when using UAC in default mode. In the end, your only protection is your AV.

    Ways to avoid this risk:

    • Elevating on a new console either per-command (using -n/--new) or force it using config setting NewWindow.Force.
    • Experimental setting SecurityEnforceUacIsolation:
      makes the elevated command run redirected, w/input redirected to NULL. Hence it will be non-interactive, so nobody will be able to drive it. Enable with gsudo config SecurityEnforceUacIsolation true

  • Abusing an active gsudo's Credentials Cache to elevate a process silently:

    The Credentials Cache allows many elevations with only one UAC popup. But there is a reason why the cache is disabled by default.

    When the cache is active, it allows elevation from one invoker process and its children, which are running at the unprotected medium integrity level. A malicious process also at medium level can inject it's code into an allowed process and make it call gsudo to request elevation silently.

    You avoid this risk by default, by not enabling the credentials cache.

Docs Troubleshooting (`docs/docs/troubleshooting.md`)

Troubleshooting

  • After installation / upgrade. Please close your consoles and open new ones.

    • Same with error Unauthorized. (Different gsudo.exe?).

  • Be sure you have configured your shell

  • Use gsudo --debug {command} to see internal debug info.

  • Search gsudo GitHub issues or create a new one if you have identified a problem.

  • Chat on gitter

  • Chat on Discord

Known issues

  • Do not install PowerShell as a .Net global tool (i.e. with dotnet tool install --global PowerShell), because it uses a shim tool with unfixed issues. Install with any other official method instead, or with choco install pwsh, winget install Microsoft.PowerShell.

  • The elevated instances do not have access to the network shares connected on the non-elevated space. This is not a gsudo issue but how Windows works. Use --copyNS to replicate Network Shares into the elevated session, but this is not bi-directional and it's interactive (may prompt for user/password).

  • gsudo.exe can be placed on a network share and invoked as \\server\share\gsudo {command} but doesn't work if your current folder is a network drive. For example do not map \\server\share\ to Z: and then Z:\>gsudo do-something.

Docs Tips Category .Json (`docs/docs/tips/_category_.json`)

{
"label": "Tips & Hacks",
"position": 6
}

Docs Tips Elevation In New Window (`docs/docs/tips/elevation-in-new-window.md`)

As mentioned in Security Considerations, elevation in the same console exposes a mild risk. You can avoid it altogether by elevating in a new console window, for example by adding the --new or -n switch.

In gsudo v2, a new setting was introduced to force elevations in a new window. To enable it simply run:

powershell
gsudo config NewWindow.Force true

The problem with this approach is that some elevations complete too quickly and the new window may close abruptly. So to leave time to verify the window result combine it with one of the following new switches:

  • --KeepWindow: After running a command in a new console, ask for keypress before closing the console/window.
  • --KeepShell: After running a command, keep the elevated shell open.

You set one of those switches permanently by using the following setting:

powershell
gsudo config NewWindow.CloseBehaviour [ KeepShellOpen | PressKeyToClose | OsDefault ]

Valid values are:

  • KeepShellOpen: Forces --keepShell. Keep the elevated shell open after running the command.

  • PressKeyToClose: Forces --keepWindow. Asks for a keypress before closing the window.

  • OsDefault: (default) Launch the command and let the operating system close it or keep it according to the system defaults (typically the window will close).

Docs Tips Mixed Elevation In Windows Terminal (`docs/docs/tips/mixed-elevation-in-windows-terminal.md`)

Mixed Elevation of tabs

You can have an elevated tab inside Windows Terminal using gsudo. Just add a new profile (or edit an existing one), edit your command and prepend gsudo . Or just put gsudo cmd or gsudo pwsh as your command.

However, I personally prefer to not do this and use the following alternative.

Elevate on demand

Use gsudo's ability to elevate the current shell in the current window. Just run gsudo and it will invoke caller shell (CMD, PowerShell, etc) elevated. Or even better, prepend gsudo to elevate specific commands.

Docs Tips Script Self Elevation (`docs/docs/tips/script-self-elevation.md`)

Self Elevate Script

You may want to create a script that always runs elevated. The following scripts will detect if the session is not elevated and then call themselves using gsudo.

Prefer using gsudo status to test if the session is elevated, as alternatives such as whoami vary depending on the OS language, and net session may fail when the network is down.

  • Cmd Batch file, long version: (e.g. self-elevate.bat) link

    batch
    @echo off
gsudo status IsElevated --no-output && goto :IsElevated

echo Admin rights needed. Elevating using gsudo.
gsudo "%~f0" %*
if errorlevel 999 Echo Failed to elevate!
exit /b %errorlevel%

:IsElevated
:: You are elevated here. Do admin stuff.

  • One-Line version: link

    batch
    @gsudo status IsElevated --no-output || (gsudo "%~f0" & exit /b)
:: You are elevated here. Do admin stuff.

  • PowerShell: (e.g. self-elevate.ps1) link

    powershell
    function Test-IsElevated {
  return (New-Object Security.Principal.WindowsPrincipal(
    [Security.Principal.WindowsIdentity]::GetCurrent()))
    .IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
}

if ((Test-IsElevated) -eq $false) {
  Write-Warning "This script requires local admin privileges. Elevating..."
  gsudo "& '$($MyInvocation.MyCommand.Source)'" $args
  if ($LastExitCode -eq 999 ) {
    Write-error 'Failed to elevate.'
  }
  return
}

# You are elevated. Do admin stuff here.

    If you don't have gsudo installed, you can still self-elevate but in a new console window: link

    batch
    @echo off
:: This script performs self-elevation, in a new console using only built-in windows tools.
:: Detect elevation using 'net session', jump to :ElevatedTasks if we are admin.
net session >nul 2>nul & net session >nul 2>nul && goto :ElevatedTasks
echo Admin rights needed. Elevating using powershell...

:: This powershell command re-executes this script in a new elevated console
powershell -C start-Process "%~f0" -Verb RunAs -ArgumentList \"%* \""
IF ERRORLEVEL 1 Echo Elevation failed!
exit /b

:ElevatedTasks
:: You are elevated here. Add your admin tasks here.
:: This will run as admin ::

Detect if running elevated

  • PowerShell-native method:

    powershell
    function Test-IsElevated {
  return (New-Object Security.Principal.WindowsPrincipal(
    [Security.Principal.WindowsIdentity]::GetCurrent()))
    .IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
}

Even when this code looks like it will check if the current user is member of the local admins group (regardless of current elevation status), instead it just returns $true if elevated.

  • PowerShell gsudo method:

    powershell
    $IsElevated = 'true' -eq (gsudo status IsElevated)

  • Cmd Batch:

    batch
    gsudo status IsElevated --no-output 
if errorlevel 0 echo Current Process Is Not Elevated
if errorlevel 1 echo Current Process Is Elevated

Detect if current user is member of admins group (regardless of current elevation status)

If you want to know if the current user can elevate with a UAC popup but without entering other user credentials, you need to check if the user is a member of S-1-5-32-544 (a.k.a. BUILTIN\Administrators for english OS).

  • Batch with gsudo:

    batch
    gsudo status IsAdminMember --no-output 
if errorlevel 1 goto IsAdminMember

  • Batch without gsudo:

    batch
    whoami /groups | findstr S-1-5-32-544 > nul
if errorlevel 1 goto IsAdmin
echo Not Admin
exit /b
:IsAdmin
echo Current user is a member of the Local Admins group. But we don't know if this session is elevated.

  • PowerShell Native

    powershell
    function Test-IsMemberOfLocalAdminsGroup {
([System.Security.Principal.WindowsIdentity]::GetCurrent()).Claims.Value -contains "S-1-5-32-544"
}

  • PowerShell with gsudo

    powershell
    $IsAdminMember = 'true' -eq (gsudo status IsAdminMember)

Docs Usage Category .Json (`docs/docs/usage/_category_.json`)

{
"label": "How to Use",
"position": 3
}

Docs Usage Mingw Msys2 (`docs/docs/usage/mingw-msys2.md`)

id: bash-for-windows sidebar_position: 4 hide_title: true title: Usage from Bash for Windows

Usage from Bash for Windows (MinGW / MSYS2 / Git-Bash / Cygwin)

Prepend gsudo to elevate bash commands (unless -d is used to elevate CMD commands).

Bash Profile Config

There is an issue with bash for windows shells: The process tree is split when invoking bash scripts such as the gsudo wrapper, that invalidates the Credentials Cache.
You need to add this function to your .bashrc profile (to skip the wrapper):

bash
gsudo() { WSLENV=WSL_DISTRO_NAME:USER:$WSLENV MSYS_NO_PATHCONV=1 gsudo.exe "$@"; }

It looks like I missed a semi-colon ; but I didn't.

Docs Usage Powershell (`docs/docs/usage/powershell.md`)

Usage from PowerShell

:::caution

If you installed PowerShell Core as a dotnet global tool you will have issues.

You can check by running dotnet tool list --global. If so, uninstall and use any another installation method such as: winget install Microsoft.PowerShell / choco install pwsh / Download from GitHub / Microsoft Store

:::

When the current shell is PowerShell, gsudo can be used in the following ways:

  • Call gsudo to start an elevated PowerShell session.

  • To elevate a command, any of the following syntaxes:

    1. gsudo { ScriptBlock } => Best performance.
    2. Invoke-gsudo function wrapper with PowerShell native syntax.
    3. gsudo 'string command' => Old, legacy syntax.

  • You can add gsudo PowerShell Module to your $PROFILE

    • This allows tab-key auto-completition. For example, write 'gsudothenspaceand thentab` and your last executed command will be suggested.
    • Also enables to use gsudo !! to elevate last command.

  • In a pipeline of commands, gsudo only elevates one command.

    command1 | gsudo elevatedCommand2 | command3

    Or you can elevate the whole pipeline if you put it inside a script block as in: gsudo {command1 | command2 | command3}

  • gsudo uses PowerShell's built-in serialization, which can be really slow with big object graphs, like all the machine process tree returned by Get-Process.

Using `gsudo {ScriptBlock}` syntax

powershell
# Syntax:
gsudo [-nwskd] [--loadProfile] 
      [-u|--user {username}] [--integrity {i}] [--ti]
      { ScriptBlock } [-args $argument1[..., $argumentN]] ;

  • Express the command to elevate as a PowerShell ScriptBlock, between {braces}. PowerShell will parse it and auto-complete commands.

  • The ScriptBlock can use literals, but can't access parent or global scope variables (remember it runs in another process). To parametrize the script, you can pass values with -args parameter and access them via $args array. If you find this painfull, try Invoke-gsudo.

  • If the result is not captured in a variable, you get best performance, as all serialization is avoided (the output is print in the console).

    powershell
    gsudo { Get-Process "chrome" }
gsudo { Get-Process $args } -args "chrome"
gsudo { echo $args[0] $args[1] } -args "Hello", "World"

  • If the result is captured, serialization is slower but automatic & transparent (you receive PSObjects).

    powershell
    $services = gsudo { Get-Service 'WSearch', 'Winmgmt'} 
Write-Output $services.DisplayName

  • Pipeline input:

    • Must be explicitly mapped with $input
    • If marshaling doesn't work as intended, try Invoke-gsudo
    powershell
    get-process winword | gsudo { $input | Stop-Process }

Example:

powershell
$file='C:\My Secret.txt'; 
$algorithm='md5';

$hash = gsudo {(Get-FileHash $args[0] -Algorithm $args[1]).Hash} -args $file, $algorithm

Using `Invoke-gsudo` function:

powershell
# Syntax:
Invoke-Gsudo [-ScriptBlock] <ScriptBlock> 
            [[-ArgumentList] <Object[]>] 
            [-InputObject <PSObject>] 
            [-LoadProfile | -NoProfile <# default #>] 
            [-Credential <PSCredential>]

# Example:
$MyString = "Hello World"
Invoke-Gsudo { Write-Output $using:MyString }

Invoke-gsudo is a wrapper function of gsudo with the following characteristics:

  • Native PowerShell function syntax.

  • Automatic serialization of inputs, outputs and pipeline objects. The results are serialized and returned (as a PSObject or PSObject[]). The serialization is mandatory so this can be slower than gsudo {ScriptBlock} syntax.

  • The command can't access parent or global scope variables. To parametrize the script, you can:

    • 🚀 Mention your $variable as $using:variableName and its serialized value will be applied.
    • Pass values with -args parameter and access them via $args array.

  • Your current context is better preserved and forwarded to the elevated process:

    • Current Location for non-FileSystem providers.
    • $ErrorActionPreference.

  • If your command requires accessing a function on your $PROFILE add the -LoadProfile parameter. See More.

  • Add -Credential to specify a user & password to run.

Examples:

powershell
# Accepts pipeline input.
Get-process SpoolSv | Invoke-gsudo { Stop-Process -Force }

# Variable usage
$folder = "C:\ProtectedFolder"
Invoke-gsudo { Remove-Item $using:folder }

# The result is serialized (PSObject) with properties.
(Invoke-gsudo { Get-ChildItem $using:folder }).LastWriteTime

Using `gsudo 'command'` syntax

  • This is the old syntax. Is still supported but not recommended.
  • Prepend gsudo, your command must be surrounded by quotes if it contains in of '"
  • Express the command to elevate as a string literal (between 'quotes'). (And properly escaping your quotes, if needed).
  • Outputs are strings, not PSObjects.
  • The command can use literals, but can't access parent or global scope variables. To parametrize the script, you can use string substitution:
powershell
$file='C:\My Secret.txt'; 
$algorithm='md5';

$hash = gsudo "(Get-FileHash '$file' -Algorithm $algorithm).Hash"

Test elevation success

powershell
# Test gsudo success (optional)
if ($LastExitCode -eq 999 ) {
    'gsudo failed to elevate!'
} elseif ($LastExitCode) {
    'Command failed!'
} else { 'Success!' }

Elevate CMD Commands

Use gsudo -d {command} to tell gsudo that your command does not requires a new instance of PowerShell to interpret it.

powershell
gsudo -d dir C:\

gsudo PowerShell Module {#powershell-profile-config}

For an enhanced experience, import gsudoModule.psd1. This is optional and enables gsudo !!, and param auto-complete for Invoke-Gsudo command.

Add the following line to your $PROFILE (replace with full path)

powershell
Import-Module 'gsudoModule.psd1'

# Or let the following line do it for you run:
Write-Output "`nImport-Module `"gsudoModule`"" | Add-Content $PROFILE

:::tip

  • You can create a custom alias for gsudo or Invoke-gsudo by adding one of these lines to your $PROFILE:
    • Set-Alias 'sudo' 'gsudo' or
    • Set-Alias 'sudo' 'Invoke-gsudo'
      :::

Loading your PS Profile on command elevations

When elevating commands, elevation is called with the -NoProfile argument. This means the elevated instance won't load your $PROFILE. If your command requires your PowerShell profile loaded you can:

  • Per command, when using gsudo, infix --loadProfile:

    powershell
    PS C:\> gsudo --loadProfile { echo (1+1) }

  • Per command, when using Invoke-gsudo, add -LoadProfile:

    powershell
    PS C:\> Invoke-Gsudo { echo (1+1) } -LoadProfile

  • Set as a permanent setting with: gsudo config PowerShellLoadProfile true

Docs Usage Usage (`docs/docs/usage/usage.md`)

How to Use

Note: You can use anywhere the sudo alias created by the installers.

powershell
gsudo [options]                  # Elevates your current shell
gsudo [options] {command} [args] # Runs {command} with elevated permissions
gsudo cache [on | off | help]    # Starts/Stops an elevated cache session. (reduced UAC popups)
gsudo status [--json | filter ]  # Shows current user, cache and console status.
gsudo !!                         # Re-run last command as admin. (YMMV)
text
/* Detailed source-code truncated for AI context efficiency. */

Examples:

powershell
gsudo   # elevates the current shell in the current console window (Supports Cmd/PowerShell/Pwsh Core/Yori/Take Command/git-bash/cygwin)
gsudo -n # launch the current shell elevated in a new console window
gsudo -n -w powershell ./Do-Something.ps1 # launch in new window and wait for exit
gsudo notepad %windir%\system32\drivers\etc\hosts # launch windows app

sudo notepad # sudo alias built-in

# redirect/pipe input/output/error example
gsudo dir | findstr /c:"bytes free" > FreeSpace.txt

gsudo config LogLevel "Error"          # Configure Reduced logging
gsudo config Prompt "$P [elevated]$G " # Configure a custom Elevated Prompt
gsudo config Prompt --reset            # Reset to default value

# Enable credentials cache (less UAC popups):
gsudo config CacheMode Auto

Configuration

powershell
gsudo config                          # Show current config settings & values.
 gsudo config {key} [--global] [value] # Read or write a user setting
 gsudo config {key} [--global] --reset # Reset config to default value
 --global                              # Affects all users (overrides user settings)

Docs Usage Wsl (`docs/docs/usage/wsl.md`)

Usage from WSL

On WSL (Windows Subsystem for Linux), elevation and root are different concepts. root allows full administration of WSL but not the Windows system. Use WSL's native su or sudo to gain root access. To get admin privilege on the Windows box you need to elevate the WSL.EXE process. gsudo allows that (a UAC popup will appear).

On WSL bash, prepend gsudo to elevate WSL commands or gsudo -d for CMD commands.

bash
# elevate default shell
PC:~$ gsudo 

# run elevated WSL command
PC:~$ gsudo mkdir /mnt/c/Windows/MyFolder

# run elevated Windows command
PC:~$ gsudo -d notepad C:/Windows/System32/drivers/etc/hosts
PC:~$ gsudo -d "notepad C:\Windows\System32\drivers\etc\hosts"
PC:~$ gsudo -d "echo 127.0.0.1 www.MyWeb.com >> %windir%\System32\drivers\etc\hosts"

# test for gsudo and command success
retval=$?;
if [ $retval -eq 0 ]; then
    echo "Success";
elif [ $retval -eq $((999 % 256)) ]; then # gsudo failure exit code (999) is read as 231 on wsl (999 mod 256)
    echo "gsudo failed to elevate!";
else
    echo "Command failed with exit code $retval";
fi;

Src Pages Markdown Page (`docs/src/pages/markdown-page.md`)

title: Markdown page example

Markdown page example

You don't need React to write simple standalone pages.

Src Pages Sponsor (`docs/src/pages/sponsor.md`)

hide_title: true title: Sponsor

Hi, I'm Gerardo, a seasoned software developer from Argentina with a journey in programming that began at the age of 15. My passion for technology led me to create 'gsudo', an open-source project that enhances the windows desktop.

Through sponsorship, you can help sustain the ongoing development of 'gsudo', including keeping it updated, adding new features, and potentially kickstarting new projects. Your support will address practical needs like covering code-signing certificate costs and other expenses, enabling me to focus on innovation and development.

gsudo is delivered as a signed application. This ensures the UAC popup doesn't show "Untrusted Publisher", and protects end users detect that gsudo binaries hadn´t been altered.

On Nov 2022, Parag Mehta @parag_c_mehta gifted me a code signing certificate which expires in Nov 2025. We have some months left to collect $632 for another 3 year renewal.

How to donate:

💵 Via GitHub Sponsors

💵 One time, or recurring donations via PayPal or Debit/Credit Card

💵 BTC 33LVf9Ek9hg5dQYf1EFWUoJaF5W3tWrrhZ

💵 ETH/USDC/USDT/SHIB 0x3c207f47a80b6feede8e9546ea1ca68635652452

--- METRICS ---

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#command-line Browse command-line catalog → #elevate Browse elevate catalog → #elevated-commands Browse elevated-commands catalog → #elevated-permissions Browse elevated-permissions catalog → #powershell Browse powershell catalog → #runas Browse runas catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →