aspnetcore/client-side/libman/libman-cli.md
Library Manager (LibMan) is a lightweight, client-side library acquisition tool. LibMan downloads popular libraries and frameworks from the file system or from a content delivery network (CDN). The supported CDNs include CDNJS, jsDelivr, and unpkg. The selected library files are fetched and placed in the appropriate location within the ASP.NET Core project.
The following command installs LibMan:
dotnet tool install -g Microsoft.Web.LibraryManager.Cli
A .NET Global Tool is installed from the Microsoft.Web.LibraryManager.Cli NuGet package.
libman
To view the installed LibMan version:
libman --version
To view the available CLI commands:
libman --help
The preceding command displays output similar to the following:
1.0.163+g45474d37ed
Usage: libman [options] [command]
Options:
--help|-h Show help information
--version Show version information
Commands:
cache List or clean libman cache contents
clean Deletes all library files defined in libman.json from the project
init Create a new libman.json
install Add a library definition to the libman.json file, and download the
library to the specified location
restore Downloads all files from provider and saves them to specified
destination
uninstall Deletes all files for the specified library from their specified
destination, then removes the specified library definition from
libman.json
update Updates the specified library
Use "libman [command] --help" for more information about a command.
The following sections outline the available CLI commands.
The libman init command creates a libman.json file if one doesn't exist. The file is created with the default item template content.
libman init [-d|--default-destination] [-p|--default-provider] [--verbosity]
libman init [-h|--help]
The following options are available for the libman init command:
-d|--default-destination <PATH>
A path relative to the current folder. Library files are installed in this location if no destination property is defined for a library in libman.json. The <PATH> value is written to the defaultDestination property of libman.json.
-p|--default-provider <PROVIDER>
The provider to use if no provider is defined for a given library. The <PROVIDER> value is written to the defaultProvider property of libman.json. Replace <PROVIDER> with one of the following values:
[!INCLUDE LibMan provider names]
[!INCLUDE standard-cli-options]
To create a libman.json file in an ASP.NET Core project:
Navigate to the project root.
Run the following command:
libman init
Type the name of the default provider, or press Enter to use the default CDNJS provider. Valid values include:
[!INCLUDE LibMan provider names]
A libman.json file is added to the project root with the following content:
{
"version": "1.0",
"defaultProvider": "cdnjs",
"libraries": []
}
The libman install command downloads and installs library files into the project. A libman.json file is added if one doesn't exist. The libman.json file is modified to store configuration details for the library files.
libman install <LIBRARY> [-d|--destination] [--files] [-p|--provider] [--verbosity]
libman install [-h|--help]
LIBRARY
The name of the library to install. This name may include version number notation (for example, @1.2.0).
The following options are available for the libman install command:
-d|--destination <PATH>
The location to install the library. If not specified, the default location is used. If no defaultDestination property is specified in libman.json, this option is required.
Note: There are limitations to the destination path. For example, when the package source has a full project structure and not just the distribution folder, you can't specify moving a folder. For more information, see Issue #407 and Issue #702
--files <FILE>
Specify the name of the file to install from the library. If not specified, all files from the library are installed. Provide one --files option per file to be installed. Relative paths are supported too. For example: --files dist/browser/signalr.js.
-p|--provider <PROVIDER>
The name of the provider to use for the library acquisition. Replace <PROVIDER> with one of the following values:
[!INCLUDE LibMan provider names]
If not specified, the defaultProvider property in libman.json is used. If no defaultProvider property is specified in libman.json, this option is required.
[!INCLUDE standard-cli-options]
Consider the following libman.json file:
{
"version": "1.0",
"defaultProvider": "cdnjs",
"libraries": []
}
To install the jQuery version 3.2.1 jquery.min.js file to the wwwroot/scripts/jquery folder using the CDNJS provider:
libman install [email protected] --provider cdnjs --destination wwwroot/scripts/jquery --files jquery.min.js
The libman.json file resembles the following:
{
"version": "1.0",
"defaultProvider": "cdnjs",
"libraries": [
{
"library": "[email protected]",
"destination": "wwwroot/scripts/jquery",
"files": [
"jquery.min.js"
]
}
]
}
To install the calendar.js and calendar.css files from C:\temp\contosoCalendar\ using the file system provider:
libman install C:\temp\contosoCalendar\ --provider filesystem --files calendar.js --files calendar.css
The following prompt appears for two reasons:
libman.json file doesn't contain a defaultDestination property.libman install command doesn't contain the -d|--destination option.After accepting the default destination, the libman.json file resembles the following:
{
"version": "1.0",
"defaultProvider": "cdnjs",
"libraries": [
{
"library": "[email protected]",
"destination": "wwwroot/scripts/jquery",
"files": [
"jquery.min.js"
]
},
{
"library": "C:\\temp\\contosoCalendar\\",
"provider": "filesystem",
"destination": "wwwroot/lib/contosoCalendar",
"files": [
"calendar.js",
"calendar.css"
]
}
]
}
The libman restore command installs library files defined in libman.json. The following rules apply:
libman.json file exists in the project root, an error is returned.defaultProvider property in libman.json is ignored.defaultDestination property in libman.json is ignored.libman restore [--verbosity]
libman restore [-h|--help]
The following options are available for the libman restore command:
[!INCLUDE standard-cli-options]
To restore the library files defined in libman.json:
libman restore
The libman clean command deletes library files previously restored via LibMan. Folders that become empty after this operation are deleted. The library files' associated configurations in the libraries property of libman.json aren't removed.
libman clean [--verbosity]
libman clean [-h|--help]
The following options are available for the libman clean command:
[!INCLUDE standard-cli-options]
To delete library files installed via LibMan:
libman clean
The libman uninstall command:
libman.json.libman.json.An error occurs when:
libman.json file exists in the project root.If more than one library with the same name is installed, you're prompted to choose one.
libman uninstall <LIBRARY> [--verbosity]
libman uninstall [-h|--help]
LIBRARY
The name of the library to uninstall. This name may include version number notation (for example, @1.2.0).
The following options are available for the libman uninstall command:
[!INCLUDE standard-cli-options]
Consider the following libman.json file:
To uninstall jQuery, either of the following commands succeed:
libman uninstall jquery
libman uninstall [email protected]
To uninstall the Lodash files installed via the filesystem provider:
libman uninstall C:\temp\lodash\
The libman update command updates a library installed via LibMan to the specified version.
An error occurs when:
libman.json file exists in the project root.If more than one library with the same name is installed, you're prompted to choose one.
libman update <LIBRARY> [-pre] [--to] [--verbosity]
libman update [-h|--help]
LIBRARY
The name of the library to update.
The following options are available for the libman update command:
-pre
Obtain the latest prerelease version of the library.
--to <VERSION>
Obtain a specific version of the library.
[!INCLUDE standard-cli-options]
To update jQuery to the latest version:
libman update jquery
To update jQuery to version 3.3.1:
libman update jquery --to 3.3.1
To update jQuery to the latest prerelease version:
libman update jquery -pre
The libman cache command manages the LibMan library cache. The filesystem provider doesn't use the library cache.
libman cache clean [<PROVIDER>] [--verbosity]
libman cache list [--files] [--libraries] [--verbosity]
libman cache [-h|--help]
PROVIDER
Only used with the clean command. Specifies the provider cache to clean. Valid values include:
[!INCLUDE LibMan provider names]
The following options are available for the libman cache command:
--files
List the names of files that are cached.
--libraries
List the names of libraries that are cached.
[!INCLUDE standard-cli-options]
To view the names of cached libraries per provider, use one of the following commands:
libman cache list
libman cache list --libraries
Output similar to the following is displayed:
Cache contents:
---------------
unpkg:
knockout
react
vue
cdnjs:
font-awesome
jquery
knockout
lodash.js
react
To view the names of cached library files per provider:
libman cache list --files
Output similar to the following is displayed:
Cache contents:
---------------
unpkg:
knockout:
<list omitted for brevity>
react:
<list omitted for brevity>
vue:
<list omitted for brevity>
cdnjs:
font-awesome
metadata.json
jquery
metadata.json
3.2.1\core.js
3.2.1\jquery.js
3.2.1\jquery.min.js
3.2.1\jquery.min.map
3.2.1\jquery.slim.js
3.2.1\jquery.slim.min.js
3.2.1\jquery.slim.min.map
3.3.1\core.js
3.3.1\jquery.js
3.3.1\jquery.min.js
3.3.1\jquery.min.map
3.3.1\jquery.slim.js
3.3.1\jquery.slim.min.js
3.3.1\jquery.slim.min.map
knockout
metadata.json
3.4.2\knockout-debug.js
3.4.2\knockout-min.js
lodash.js
metadata.json
4.17.10\lodash.js
4.17.10\lodash.min.js
react
metadata.json
Notice the preceding output shows that jQuery versions 3.2.1 and 3.3.1 are cached under the CDNJS provider.
To empty the library cache for the CDNJS provider:
libman cache clean cdnjs
After emptying the CDNJS provider cache, the libman cache list command displays the following:
Cache contents:
---------------
unpkg:
knockout
react
vue
cdnjs:
(empty)
To empty the cache for all supported providers:
libman cache clean
After emptying all provider caches, the libman cache list command displays the following:
Cache contents:
---------------
unpkg:
(empty)
cdnjs:
(empty)