commit bb0626d368e763a28daef1724f383a16b9c8f6cf
parent cd8e9920bcd5cc28bf9cb1217a82847352da0e09
Author: NotBacon <KKart2007@gmail.com>
Date: Mon, 20 Nov 2023 08:33:08 -0800
Update docs for winget commands (#3909)
Added new command flags, aliases, and updated usage for winget commands.
To match latest version of winget
<!-- To check a checkbox place an "x" between the brackets. e.g: [x] -->
- [x] I have signed the [Contributor License
Agreement](https://cla.opensource.microsoft.com/microsoft/winget-pkgs).
- [x] This pull request is related to an issue. (talked about outdated
docs briefly here #3263, also #3639)
-----
###### Microsoft Reviewers: [Open in
CodeFlow](https://microsoft.github.io/open-pr/?codeflow=https://github.com/microsoft/winget-cli/pull/3909)
Diffstat:
12 files changed, 165 insertions(+), 39 deletions(-)
diff --git a/doc/windows/package-manager/winget/export.md b/doc/windows/package-manager/winget/export.md
@@ -35,6 +35,12 @@ The options allow you to customize the export experience to meet your needs.
|--------|-------------|
| **-s, --source** | [optional] Specifies a source to export files from. Use this option when you only want files from a specific source. |
| **--include-versions** | [optional] Includes the version of the app currently installed. Use this option if you want a specific version. By default, unless specified, [**import**](import.md) will use latest. |
+| **--accept-source-agreements** | Accept all source agreements during source operations |
+| **-?, --help** | Shows help about the selected command |
+| **--wait** | Prompts the user to press any key before exiting |
+| **--logs, --open-logs** | Open the default logs location |
+| **--verbose, --verbose-logs** | Enables verbose logging for winget |
+| **--disable-interactivity** | Disable interactive prompts |
## JSON Schema
The driving force behind the **export** command is the JSON file. As mentioned, you can find the schema for the JSON file [here](https://aka.ms/winget-packages.schema.1.0.json).
diff --git a/doc/windows/package-manager/winget/hash.md b/doc/windows/package-manager/winget/hash.md
@@ -24,9 +24,21 @@ The following arguments are available:
| Argument | Description |
|--------------|-------------|
-| **-f,--file** | The path to the file to be hashed. |
-| **-m,--msix** | Specifies that the hash command will also create the SHA-256 SignatureSha256 for use with MSIX installers. |
+| **-f, --file** | The path to the file to be hashed. |
+
+## Options
+
+The following options are available:
+
+| Option | Description |
+|--------|-------------|
+| **-m, --msix** | Specifies that the hash command will also create the SHA-256 SignatureSha256 for use with MSIX installers. |
| **-?, --help** | Gets additional help on this command. |
+| **--wait** | Prompts the user to press any key before exiting |
+| **--logs, --open-logs** | Open the default logs location |
+| **--verbose, --verbose-logs** | Enables verbose logging for winget |
+| **--disable-interactivity** | Disable interactive prompts |
+
## Related topics
diff --git a/doc/windows/package-manager/winget/import.md b/doc/windows/package-manager/winget/import.md
@@ -23,7 +23,7 @@ The **import** command is often used to share your developer environment or buil
The following arguments are available.
| Argument | Description |
|-------------|-------------|
-| **-i,--import-file** | JSON file describing the packages to install
+| **-i, --import-file** | JSON file describing the packages to install
## Options
@@ -33,6 +33,14 @@ The options allow you to customize the import experience to meet your needs.
|-------------|-------------|
| **--ignore-unavailable** | Suppresses errors if the app requested is unavailable |
| **--ignore-versions** | Ignores versions specified in the JSON file and installs the latest available version |
+| **--no-upgrade** | Skips upgrade if an installed version already exists |
+| **--accept-package-agreements** | Accept all license agreements for packages |
+| **--accept-source-agreements** | Accept all source agreements during source operations |
+| **-?, --help** | Shows help about the selected command |
+| **--wait** | Prompts the user to press any key before exiting |
+| **--logs, --open-logs** | Open the default logs location |
+| **--verbose, --verbose-logs** | Enables verbose logging for winget |
+| **--disable-interactivity** | Disable interactive prompts |
## JSON Schema
The driving force behind the **import** command is the JSON file. You can find the schema for the JSON file [here](https://aka.ms/winget-packages.schema.1.0.json).
diff --git a/doc/windows/package-manager/winget/index.md b/doc/windows/package-manager/winget/index.md
@@ -45,7 +45,6 @@ One of the most common usage scenarios is to search for and install a favorite t
### Commands
The current preview of the **winget** tool supports the following commands.
-
| Command | Description |
|---------|-------------|
| [install](install.md) | Installs the specified application. |
@@ -61,6 +60,9 @@ The current preview of the **winget** tool supports the following commands.
| [features](features.md) | Shows the status of experimental features. |
| [export](export.md) | Exports a list of the installed packages. |
| [import](import.md) | Installs all the packages in a file. |
+| pin | Manage package pins. |
+| configure | Configures the system into a desired state. |
+| download | Downloads the installer from a given package. |
### Options
@@ -72,6 +74,9 @@ The current version of the **winget** tool supports the following options.
| **--info** | Provides you with all detailed information on winget, including the links to the license, privacy statement, and configured group policies. |
| **-?, --help** | Shows additional help for winget. |
| **--wait** | Waits for user input upon command completion. |
+| **--logs,--open-logs** | Open the default logs location |
+| **--verbose,--verbose-logs** | Enables verbose logging for winget |
+| **--disable-interactivity** | Disable interactive prompts |
## Supported installer formats
diff --git a/doc/windows/package-manager/winget/install.md b/doc/windows/package-manager/winget/install.md
@@ -16,6 +16,9 @@ The **install** command requires that you specify the exact string to install. I
`winget install [[-q] <query>] [<options>]`
+The following command aliases are available: \
+`add`
+
## Arguments
@@ -24,8 +27,7 @@ The following arguments are available.
| Argument | Description |
|-------------|-------------|
-| **-q,--query** | The query used to search for an app. |
-| **-?, --help** | Get additional help on this command. |
+| **-q, --query** | The query used to search for an app. |
## Options
@@ -47,6 +49,26 @@ The options allow you to customize the install experience to meet your needs.
| **--override** | A string that will be passed directly to the installer. |
| **-l, --location** | Location to install to (if supported). |
| **--force** | Override the installer hash check. |
+| **-a, --architecture** | Select the architecture |
+| **--installer-type** | Select the installer type |
+| **--locale** | Locale to use (BCP47 format) |
+| **--custom** | Arguments to be passed on to the installer in addition to the defaults |
+| **--ignore-security-hash** | Ignore the installer hash check failure |
+| **--skip-dependencies** | Skip processing package dependencies and Windows features |
+| **--ignore-local-archive-malware-scan** | Ignore the malware scan performed as part of installing an archive-type package from a local manifest |
+| **--dependency-source** | Find package dependencies using the specified source |
+| **--accept-package-agreements** | Accept all license agreements for packages |
+| **--no-upgrade** | Skip upgrade if an installed version already exists |
+| **--header** | Optional Windows-Package-Manager REST source HTTP header |
+| **--accept-source-agreements** | Accept all source agreements during source operations |
+| **-r, --rename** | The value to rename the executable file (portable) |
+| **--uninstall-previous** | Uninstall the previous version of the package during the upgrade |
+| **--ignore-interactivity** | Disable interactive prompts |
+| **-?, --help** | Get additional help on this command. |
+| **--wait** | Prompts the user to press any key before exiting |
+| **--logs, --open-logs** | Open the default logs location |
+| **--verbose, --verbose-logs** | Enables verbose logging for winget |
+| **--disable-interactivity** | Disable interactive prompts |
### Example queries
diff --git a/doc/windows/package-manager/winget/list.md b/doc/windows/package-manager/winget/list.md
@@ -18,6 +18,9 @@ The **list** command also supports filters which can be used to limit your list
`winget list [[-q] <query>] [<options>]`
+The following command aliases are available: \
+`ls`
+
## Arguments
@@ -27,22 +30,31 @@ The following arguments are available.
| Argument | Description |
|-------------|-------------|
| **-q,--query** | The query used to search for an app. |
-| **-?, --help** | Get additional help on this command. |
## Options
The options allow you to customize the list experience to meet your needs.
-
-| Option | Description |
-|-------------|-------------|
-| **--id** | Limits the list to the ID of the application. |
-| **--name** | Limits the list to the name of the application. |
-| **--moniker** | Limits the list to the moniker listed for the application. |
+| Option | Description |
+|--------|-------------|
+| **--id** | Limits the list to the ID of the application. |
+| **--name** | Limits the list to the name of the application. |
+| **--moniker** | Limits the list to the moniker listed for the application. |
| **-s, --source** | Restricts the list to the source name provided. Must be followed by the source name. |
| **--tag** | Filters results by tags. |
| **--command** | Filters results by command specified by the application. |
| **-n, --count** | Limits the number of apps displayed in one query. |
-| **-e, --exact** | Uses the exact string in the list query, including checking for case-sensitivity. It will not use the default behavior of a substring. |
+| **-e, --exact** | Uses the exact string in the list query, including checking for case-sensitivity. It will not use the default behavior of a substring. |
+| **--scope** | Select installed package scope filter (user or machine). |
+| **--header** | Optional Windows-Package-Manager REST source HTTP header. |
+| **--accept-source-agreements** | Accept all source agreements during source operations. |
+| **--upgrade-available** | Lists only packages which have an upgrade available. |
+| **-u,--unknown,--include-unknown** | List packages even if their current version cannot be determined. Can only be used with the --upgrade-available argument. |
+| **--pinned,--include-pinned** | List packages even if they have a pin that prevents upgrade. Can only be used with the --upgrade-available argument. |
+| **-?,--help** | Get additional help on this command. |
+| **--wait** | Prompts the user to press any key before exiting. |
+| **--logs,--open-logs** | Open the default logs location. |
+| **--verbose,--verbose-logs** | Enables verbose logging for winget. |
+| **--disable-interactivity** | Disable interactive prompts. |
### Example queries
diff --git a/doc/windows/package-manager/winget/search.md b/doc/windows/package-manager/winget/search.md
@@ -16,6 +16,9 @@ The **search** command can show all applications available, or it can be filtere
`winget search [[-q] <query>] [<options>]`
+The following command aliases are available: \
+`find`
+
## Arguments
@@ -24,8 +27,7 @@ The following arguments are available.
| Argument | Description |
--------------|-------------|
-| **-q,--query** | The query used to search for an app. |
-| **-?, --help** | Gets additional help on this command. |
+| **-q, --query** | The query used to search for an app. |
## Show all
@@ -41,7 +43,18 @@ Search strings can be filtered with the following options.
| **--name** | Limits the search to the name of the application. |
| **--moniker** | Limits the search to the moniker specified. |
| **--tag** | Limits the search to the tags listed for the application. |
-| **--command** | Limits the search to the commands listed for the application. |
+| **--cmd, --command** | Limits the search to the commands listed for the application. |
+| **-s, --source** | Find package using the specified source. |
+| **-n, --count** | Show no more than specified number of results (between 1 and 1000). |
+| **-e, --exact** | Find package using exact match. |
+| **--header** | Optional Windows-Package-Manager REST source HTTP header. |
+| **--accept-source-agreements** | Accept all source agreements during source operations. |
+| **--versions** | Show available versions of the package. |
+| **-?, --help** | Gets additional help on this command. |
+| **--wait** | Prompts the user to press any key before exiting. |
+| **--logs, --open-logs** | Open the default logs location. |
+| **--verbose, --verbose-logs** | Enables verbose logging for winget. |
+| **--disable-interactivity** | Disable interactive prompts. |
The string will be treated as a substring. The search by default is also case insensitive. For example, `winget search micro` could return the following:
diff --git a/doc/windows/package-manager/winget/show.md b/doc/windows/package-manager/winget/show.md
@@ -16,6 +16,9 @@ The **show** command only shows metadata that was submitted with the application
`winget show [[-q] <query>] [<options>]`
+The following command aliases are available: \
+`view`
+
## Arguments
@@ -24,8 +27,7 @@ The following arguments are available.
| Argument | Description |
|--------------|-------------|
-| **-q,--query** | The query used to search for an application. |
-| **-?, --help** | Gets additional help on this command. |
+| **-q, --query** | The query used to search for an application. |
## Options
@@ -41,6 +43,17 @@ The following options are available.
| **-s,--source** | Find the application using the specified [source](source.md). |
| **-e,--exact** | Find the application using exact match. |
| **--versions** | Show available versions of the application. |
+| **--scope** | Select install scope (user or machine). |
+| **-a, --architecture** | Select the architecture. |
+| **--installer-type** | Select the installer type. |
+| **--locale** | Locale to use (BCP47 format). |
+| **--header** | Optional Windows-Package-Manager REST source HTTP header. |
+| **--accept-source-agreements** | Accept all source agreements during source operations. |
+| **-?, --help** | Gets additional help on this command. |
+| **--wait** | Prompts the user to press any key before exiting. |
+| **--logs, --open-logs** | Open the default logs location. |
+| **--verbose, --verbose-logs** | Enables verbose logging for winget. |
+| **--disable-interactivity** | Disable interactive prompts. |
## Multiple selections
diff --git a/doc/windows/package-manager/winget/source.md b/doc/windows/package-manager/winget/source.md
@@ -16,7 +16,7 @@ A source provides the data for you to discover and install applications. Only ad
## Usage
-`winget source <sub-command> <options>`
+`winget source [<command>] [<options>]`
@@ -41,16 +41,22 @@ Source supports the following sub-commands for manipulating the sources.
| **reset** | Resets **winget** back to the initial configuration. |
| **export** | Export current sources |
+For more details on a specific command, pass it the help argument. [-?]
+
## Options
The **source** command supports the following options.
| Option | Description |
|--------------|-------------|
-| **-n,--name** | The name to identify the source by. |
-| **-a,--arg** | The URL or UNC of the source. |
-| **-t,--type** | The type of source. |
+| **-n, --name** | The name to identify the source by. |
+| **-a, --arg** | The URL or UNC of the source. |
+| **-t, --type** | The type of source. |
| **-?, --help** | Gets additional help on this command. |
+| **--wait** | Prompts the user to press any key before exiting. |
+| **--logs, --open-logs** | Open the default logs location. |
+| **--verbose, --verbose-logs** | Enables verbose logging for winget. |
+| **--disable-interactivity** | Disable interactive prompts. |
## add
diff --git a/doc/windows/package-manager/winget/uninstall.md b/doc/windows/package-manager/winget/uninstall.md
@@ -14,7 +14,11 @@ The **uninstall** command requires that you specify the exact string to uninstal
## Usage
-`winget uninstall [[-q] <query>] [<options>]`
+`winget uninstall [[-q] <query>...] [<options>]`
+
+The following command aliases are available: \
+`remove` \
+`rm`
@@ -25,24 +29,35 @@ The following arguments are available.
| Argument | Description |
|-------------|-------------|
| **-q,--query** | The query used to search for an app. |
-| **-?, --help** | Get additional help on this command. |
## Options
The options allow you to customize the uninstall experience to meet your needs.
| Option | Description |
-|-------------|-------------|
+|--------|-------------|
| **-m, --manifest** | Must be followed by the path to the manifest (YAML) file. You can use the manifest to run the uninstall experience from a [local YAML file](#local-uninstall). |
-| **--id** | Limits the uninstall to the ID of the application. |
-| **--name** | Limits the search to the name of the application. |
-| **--moniker** | Limits the search to the moniker listed for the application. |
-| **-v, --version** | Enables you to specify an exact version to uninstall. If not specified, latest will uninstall the highest versioned application. |
-| **-s, --source** | Restricts the search to the source name provided. Must be followed by the source name. |
-| **-e, --exact** | Uses the exact string in the query, including checking for case-sensitivity. It will not use the default behavior of a substring. |
-| **-i, --interactive** | Runs the uninstaller in interactive mode. The default experience shows uninstaller progress. |
-| **-h, --silent** | Runs the uninstaller in silent mode. This suppresses all UI. The default experience shows uninstaller progress. |
-| **-o, --log** | Directs the logging to a log file. You must provide a path to a file that you have the write rights to. |
+| **--id** | Limits the uninstall to the ID of the application. |
+| **--name** | Limits the search to the name of the application. |
+| **--moniker** | Limits the search to the moniker listed for the application. |
+| **-v, --version** | Enables you to specify an exact version to uninstall. If not specified, the latest will uninstall the highest versioned application. |
+| **-s, --source** | Restricts the search to the source name provided. Must be followed by the source name. |
+| **-e, --exact** | Uses the exact string in the query, including checking for case-sensitivity. It will not use the default behavior of a substring. |
+| **-i, --interactive** | Runs the uninstaller in interactive mode. The default experience shows uninstaller progress. |
+| **-h, --silent** | Runs the uninstaller in silent mode. This suppresses all UI. The default experience shows uninstaller progress. |
+| **-o, --log** | Directs the logging to a log file. You must provide a path to a file that you have the write rights to. |
+| **--product-code** | Filters using the product code. |
+| **--scope** | Select installed package scope filter (user or machine). |
+| **--force** | Directly run the command and continue with non-security-related issues. |
+| **--purge** | Deletes all files and directories in the package directory (portable). |
+| **--preserve** | Retains all files and directories created by the package (portable). |
+| **--header** | Optional Windows-Package-Manager REST source HTTP header. |
+| **--accept-source-agreements** | Accept all source agreements during source operations. |
+| **-?, --help** | Get additional help on this command. |
+| **--wait** | Prompts the user to press any key before exiting. |
+| **--logs, --open-logs** | Open the default logs location. |
+| **--verbose, --verbose-logs** | Enables verbose logging for winget. |
+| **--disable-interactivity** | Disable interactive prompts. |
Once you have successfully identified the application intended to uninstall, winget will execute the uninstall command. In the example below, the **name** 'orca' and the **id** was passed in.
diff --git a/doc/windows/package-manager/winget/upgrade.md b/doc/windows/package-manager/winget/upgrade.md
@@ -14,7 +14,10 @@ The **upgrade** command requires that you specify the exact string to upgrade. I
## Usage
-`winget upgrade [[-q] <query>] [<options>]`
+`winget upgrade [[-q] <query>...] [<options>]`
+
+The following command aliases are available: \
+`update`
diff --git a/doc/windows/package-manager/winget/validate.md b/doc/windows/package-manager/winget/validate.md
@@ -12,7 +12,7 @@ The **validate** command of the [winget](index.md) tool validates a [manifest](.
## Usage
-`winget validate [--manifest] <path>`
+`winget validate [--manifest] <manifest> [<options>]`
## Arguments
@@ -20,8 +20,19 @@ The following arguments are available.
| Argument | Description |
|--------------|-------------|
-| **--manifest** | the path to the manifest to be validated. |
-| **-?, --help** | get additional help on this command |
+| **--manifest** | The path to the manifest to be validated. |
+
+## Options
+
+The options allow you to customize the export experience to meet your needs.
+
+| Option | Description |
+|--------|-------------|
+| **-?, --help** | Get additional help on this command. |
+| **--wait** | Prompts the user to press any key before exiting. |
+| **--logs, --open-logs** | Open the default logs location. |
+| **--verbose, --verbose-logs** | Enables verbose logging for winget. |
+| **--disable-interactivity** | Disable interactive prompts. |
## Related topics
