ABP CLI
ABP CLI (Command Line Interface) is a command line tool to perform some common operations for ABP based solutions.
Installation
ABP CLI is a dotnet global tool. Install it using a command line window:
dotnet tool install -g Volo.Abp.Cli
To update an existing installation:
dotnet tool update -g Volo.Abp.Cli
Global Options
While each command may have a set of options, there are some global options that can be used with any command;
--skip-cli-version-check
: Skips to check the latest version of the ABP CLI. If you don't specify, it will check the latest version and shows a warning message if there is a newer version of the ABP CLI.
Commands
Here, is the list of all available commands before explaining their details:
help
: Shows help on the usage of the ABP CLI.cli
: Update or remove ABP CLI.new
: Generates a new solution based on the ABP startup templates.update
: Automatically updates all ABP related NuGet and NPM packages in a solution.clean
: Deletes allBIN
andOBJ
folders in the current folder.add-package
: Adds an ABP package to a project.add-module
: Adds a multi-package application module to a solution.list-modules
: Lists names of open-source application modules.list-templates
: Lists the names of available templates to create a solution.get-source
: Downloads the source code of a module.generate-proxy
: Generates client side proxies to use HTTP API endpoints.remove-proxy
: Removes previously generated client side proxies.switch-to-preview
: Switches to the latest preview version of the ABP Framework.switch-to-nightly
: Switches to the latest nightly builds of the ABP related packages on a solution.switch-to-stable
: Switches to the latest stable versions of the ABP related packages on a solution.switch-to-local
: Changes NuGet package references on a solution to local project references.translate
: Simplifies to translate localization files when you have multiple JSON localization files in a source control repository.login
: Authenticates on your computer with your abp.io username and password.login-info
: Shows the current user's login information.logout
: Logouts from your computer if you've authenticated before.bundle
: Generates script and style references for ABP Blazor and MAUI Blazor project.install-libs
: Install NPM Packages for MVC / Razor Pages and Blazor Server UI types.clear-download-cache
: Clears the templates download cache.trust-version
: Trusts the user's version and does not check if the version exists or not. If the template with the given version is found in the cache, it will be used, otherwise throws an exception.
help
Shows basic usages of the ABP CLI.
Usage:
abp help [command-name]
Examples:
abp help # Shows a general help.
abp help new # Shows help about the "new" command.
cli
Update or remove ABP CLI.
Usage:
abp cli [command-name]
Examples:
abp cli update
abp cli update --preview
abp cli update --version 5.0.0
abp cli remove
new
Generates a new solution based on the ABP startup templates.
Usage:
abp new <solution-name> [options]
Example:
abp new Acme.BookStore
Acme.BookStore
is the solution name here.- Common convention is to name a solution is like YourCompany.YourProject. However, you can use different naming like YourProject (single level namespacing) or YourCompany.YourProduct.YourModule (three levels namespacing).
For more samples, go to ABP CLI Create Solution Samples
Options
--template
or-t
: Specifies the template name. Default template name isapp
, which generates a web application. Available templates:app
(default): Application template. Additional options:--ui
or-u
: Specifies the UI framework. Default framework ismvc
. Available frameworks:mvc
: ASP.NET Core MVC. There are some additional options for this template:--tiered
: Creates a tiered solution where Web and Http API layers are physically separated. If not specified, it creates a layered solution which is less complex and suitable for most scenarios.
angular
: Angular UI. There are some additional options for this template:--separate-auth-server
: The Auth Server project comes as a separate project and runs at a different endpoint. It separates the Auth Server from the API Host application. If not specified, you will have a single endpoint in the server side.--pwa
: Specifies the project as Progressive Web Application.
blazor
: Blazor UI. There are some additional options for this template:--separate-auth-server
The Auth Server project comes as a separate project and runs at a different endpoint. It separates the Auth Server from the API Host application. If not specified, you will have a single endpoint in the server side.--pwa
: Specifies the project as Progressive Web Application.
blazor-server
: Blazor Server UI. There are some additional options for this template:--tiered
: The Auth Server and the API Host project comes as separate projects and run at different endpoints. It has 3 startup projects: HttpApi.Host, AuthServer and Blazor and and each runs on different endpoints. If not specified, you will have a single endpoint for your web project.
none
: Without UI. No front-end layer will be created. There are some additional options for this template:--separate-auth-server
: The Auth Server project comes as a separate project and runs at a different endpoint. It separates the Auth Server from the API Host application. If not specified, you will have a single endpoint in the server side.
--mobile
or-m
: Specifies the mobile application framework. If not specified, no mobile application will be created. Available options:react-native
: React Native.maui
: MAUI. This mobile option is only available for ABP Commercial.
--database-provider
or-d
: Specifies the database provider. Default provider isef
. Available providers:ef
: Entity Framework Core.mongodb
: MongoDB.
--theme
: Specifies the theme. Default theme isleptonx-lite
. Available themes:leptonx-lite
: LeptonX Lite Theme.basic
: Basic Theme.
module
: Module template. Additional options:--no-ui
: Specifies to not include the UI. This makes possible to create service-only modules (a.k.a. microservices - without UI).
console
: Console template.app-nolayers
: Single-layer application template. Additional options:--ui
or-u
: Specifies the UI framework. Default framework ismvc
. Available frameworks:mvc
: ASP.NET Core MVC.angular
: Angular UI.blazor
: Blazor UI.blazor-server
: Blazor Server UI.none
: Without UI.
--database-provider
or-d
: Specifies the database provider. Default provider isef
. Available providers:ef
: Entity Framework Core.mongodb
: MongoDB.
--theme
: Specifies the theme. Default theme isleptonx-lite
. Available themes:leptonx-lite
: LeptonX Lite Theme.basic
: Basic Theme.
maui
: .NET MAUI. A minimalist .NET MAUI application will be created if you specify this option.
--output-folder
or-o
: Specifies the output folder. Default value is the current directory.--version
or-v
: Specifies the ABP & template version. It can be a release tag or a branch name. Uses the latest release if not specified. Most of the times, you will want to use the latest version.--preview
: Use latest preview version.--template-source
or-ts
: Specifies a custom template source to use to build the project. Local and network sources can be used(LikeD:\local-template
orhttps://.../my-template-file.zip
).--create-solution-folder
or-csf
: Specifies if the project will be in a new folder in the output folder or directly the output folder.--connection-string
or-cs
: Overwrites the default connection strings in allappsettings.json
files. The default connection string isServer=localhost;Database=MyProjectName;Trusted_Connection=True
for EF Core and it is configured to use the SQL Server. If you want to use the EF Core, but need to change the DBMS, you can change it as described here (after creating the solution).--database-management-system
or-dbms
: Sets the database management system. Default is SQL Server. Supported DBMS's:SqlServer
MySQL
SQLite
Oracle
Oracle-Devart
PostgreSQL
--local-framework-ref --abp-path
: Uses local projects references to the ABP framework instead of using the NuGet packages. This can be useful if you download the ABP Framework source code and have a local reference to the framework from your application.--no-random-port
: Uses template's default ports.--skip-installing-libs
or-sib
: Skip installing client side packages.--skip-cache
or-sc
: Always download the latest from our server and refresh their templates folder cache.--with-public-website
: Public Website is a front-facing website for describing your project, listing your products and doing SEO for marketing purposes. Users can login and register on your website with this website.
See some examples for the new command here.
update
Updating all ABP related packages can be tedious since there are many packages of the framework and modules. This command automatically updates all ABP related NuGet and NPM packages in a solution or project to the latest versions. You can run it in the root folder of your solutions.
Usage:
abp update [options]
- If you run in a directory with a .csproj file, it updates all ABP related packages of the project to the latest versions.
- If you run in a directory with a .sln file, it updates all ABP related packages of the all projects of the solution to the latest versions.
- If you run in a directory that contains multiple solutions in sub-folders, it can update all the solutions, including Angular projects.
Note that this command can upgrade your solution from a previous version, and also can upgrade it from a preview release to the stable release of the same version.
Options
--npm
: Only updates NPM packages.--nuget
: Only updates NuGet packages.--solution-path
or-sp
: Specify the solution path. Use the current directory by default--solution-name
or-sn
: Specify the solution name. Search*.sln
files in the directory by default.--check-all
: Check the new version of each package separately. Default isfalse
.--version
or-v
: Specifies the version to use for update. If not specified, latest version is used.
clean
Deletes all BIN
and OBJ
folders in the current folder.
Usage:
abp clean
add-package
Adds an ABP package to a project by,
- Adding related nuget package as a dependency to the project.
- Adding
[DependsOn(...)]
attribute to the module class in the project (see the module development document).
Notice that the added module may require additional configuration which is generally indicated in the documentation of the related package.
Basic usage:
abp add-package <package-name> [options]
Example:
abp add-package Volo.Abp.AspNetCore.Mvc.UI.Theme.Basic
- This example adds the
Volo.Abp.AspNetCore.Mvc.UI.Theme.Basic
package to the project.
Options
--project
or-p
: Specifies the project (.csproj) file path. If not specified, CLI tries to find a .csproj file in the current directory.--with-source-code
: Downloads the source code of the package to your solution folder and uses local project references instead of NuGet/NPM packages.--add-to-solution-file
: Adds the downloaded package to your solution file, so you will also see the package when you open the solution on a IDE. (only available when--with-source-code
is True)
Currently only the source code of the basic theme packages(MVC and Blazor) can be downloaded.
- Volo.Abp.AspNetCore.Mvc.UI.Theme.Basic
- Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme
- Volo.Abp.AspNetCore.Components.Web.BasicTheme
- Volo.Abp.AspNetCore.Components.Server.BasicTheme
add-module
Adds a multi-package application module to a solution by finding all packages of the module, finding related projects in the solution and adding each package to the corresponding project in the solution.
It can also create a new module for your solution and add it to your solution. See --new
option.
A business module generally consists of several packages (because of layering, different database provider options or other reasons). Using
add-module
command dramatically simplifies adding a module to a solution. However, each module may require some additional configurations which is generally indicated in the documentation of the related module.
Usage:
abp add-module <module-name> [options]
Examples:
abp add-module Volo.Blogging
- This example adds the
Volo.Blogging
module to the solution.
abp add-module ProductManagement --new --add-to-solution-file
- This command creates a fresh new module customized for your solution (named
ProductManagement
) and adds it to your solution.
Options
--solution
or-s
: Specifies the solution (.sln) file path. If not specified, CLI tries to find a .sln file in the current directory.--skip-db-migrations
: For EF Core database provider, it automatically adds a new code first migration (Add-Migration
) and updates the database (Update-Database
) if necessary. Specify this option to skip this operation.-sp
or--startup-project
: Relative path to the project folder of the startup project. Default value is the current folder.--new
: Creates a fresh new module (customized for your solution) and adds it to your solution.--with-source-code
: Downloads the source code of the module to your solution folder and uses local project references instead of NuGet/NPM packages. This options is alwaysTrue
if--new
is used.--add-to-solution-file
: Adds the downloaded/created module to your solution file, so you will also see the projects of the module when you open the solution on a IDE. (only available when--with-source-code
isTrue
.)
list-modules
Lists names of open-source application modules.
Usage:
abp list-modules [options]
Example:
abp list-modules
Options
--include-pro-modules
: Includes commercial (pro) modules in the output.
list-templates
Lists all available templates to create a solution.
Usage:
abp list-templates
get-source
Downloads the source code of a module to your computer.
Usage:
abp get-source <module-name> [options]
Example:
abp get-source Volo.Blogging
abp get-source Volo.Blogging --local-framework-ref --abp-path D:\GitHub\abp
Options
--output-folder
or-o
: Specifies the directory that source code will be downloaded in. If not specified, current directory is used.--version
or-v
: Specifies the version of the source code that will be downloaded. If not specified, latest version is used.--preview
: If no version option is specified, this option specifies if latest preview version will be used instead of latest stable version.--local-framework-ref --abp-path
: Path of ABP Framework GitHub repository in your computer. This will be used for converting project references to your local system. If this is not specified, project references will be converted to NuGet references.
generate-proxy
Generates Angular, C# or JavaScript service proxies for your HTTP APIs to make easy to consume your services from the client side. Your host (server) application must be up and running before running this command.
Usage:
abp generate-proxy -t <client-type> [options]
Examples:
abp generate-proxy -t ng -url https://localhost:44302/
abp generate-proxy -t js -url https://localhost:44302/
abp generate-proxy -t csharp -url https://localhost:44302/
Options
--type
or-t
: The name of client type. Available clients:csharp
: C#, work in the*.HttpApi.Client
project directory. There are some additional options for this client:--without-contracts
: Avoid generating the application service interface, class, enum and dto types.--folder
: Folder name to place generated CSharp code in. Default value:ClientProxies
.
ng
: Angular. There are some additional options for this client:--api-name
or-a
: The name of the API endpoint defined in the/src/environments/environment.ts
. Default value:default
.--source
or-s
: Specifies the Angular project name to resolve the root namespace & API definition URL from. Default value:defaultProject
.--target
: Specifies the Angular project name to place generated code in. Default value:defaultProject
.--module
: Backend module name. Default value:app
.--entry-point
: Targets the Angular project to place the generated code.--url
: Specifies api definition url. Default value is API Name's url in environment file.--prompt
or-p
: Asks the options from the command line prompt (for the unspecified options).
js
: JavaScript. work in the*.Web
project directory. There are some additional options for this client:--output
or-o
: JavaScript file path or folder to place generated code in.
--module
or-m
: Specifies the name of the backend module you wish to generate proxies for. Default value:app
.--working-directory
or-wd
: Execution directory. Forcsharp
andjs
client types.--url
or-u
: API definition URL from.--service-type
or-st
: Specifies the service type to generate.application
,integration
andall
, Default value:all
for C#,application
for JavaScript / Angular.
See the Angular Service Proxies document for more.
remove-proxy
Removes previously generated proxy code from the Angular, CSharp or JavaScript application. Your host (server) application must be up and running before running this command.
This can be especially useful when you generate proxies for multiple modules before and need to remove one of them later.
Usage:
abp remove-proxy -t <client-type> [options]
Examples:
abp remove-proxy -t ng
abp remove-proxy -t js -m identity -o Pages/Identity/client-proxies.js
abp remove-proxy -t csharp --folder MyProxies/InnerFolder
Options
--type
or-t
: The name of client type. Available clients:csharp
: C#, work in the*.HttpApi.Client
project directory. There are some additional options for this client:--folder
: Folder name to place generated CSharp code in. Default value:ClientProxies
.
ng
: Angular. There are some additional options for this client:--api-name
or-a
: The name of the API endpoint defined in the/src/environments/environment.ts
. Default value:default
.--source
or-s
: Specifies the Angular project name to resolve the root namespace & API definition URL from. Default value:defaultProject
.--target
: Specifies the Angular project name to place generated code in. Default value:defaultProject
.--url
: Specifies api definition url. Default value is API Name's url in environment file.--prompt
or-p
: Asks the options from the command line prompt (for the unspecified options).
js
: JavaScript. work in the*.Web
project directory. There are some additional options for this client:--output
or-o
: JavaScript file path or folder to place generated code in.
--module
or-m
: Specifies the name of the backend module you wish to generate proxies for. Default value:app
.--working-directory
or-wd
: Execution directory. Forcsharp
andjs
client types.--url
or-u
: API definition URL from.
See the Angular Service Proxies document for more.
switch-to-preview
You can use this command to switch your solution or project to latest preview version of the ABP framework.
Usage:
abp switch-to-preview [options]
Options
--directory
or-d
: Specifies the directory. The solution or project should be in that directory or in any of its sub directories. If not specified, default is the current directory.
switch-to-nightly
You can use this command to switch your solution or project to latest nightly preview version of the ABP framework packages.
Usage:
abp switch-to-nightly [options]
Options
--directory
or-d
: Specifies the directory. The solution or project should be in that directory or in any of its sub directories. If not specified, default is the current directory.
switch-to-stable
If you're using the ABP Framework preview packages (including nightly previews), you can switch back to latest stable version using this command.
Usage:
abp switch-to-stable [options]
Options
--directory
or-d
: Specifies the directory. The solution or project should be in that directory or in any of its sub directories. If not specified, default is the current directory.
switch-to-local
Changes all NuGet package references to local project references for all the .csproj files in the specified folder (and all its subfolders with any deep). It is not limited to ABP Framework or Module packages.
Usage:
abp switch-to-local [options]
Options
--solution
or-s
: Specifies the solution directory. The solution should be in that directory or in any of its sub directories. If not specified, default is the current directory.--paths
or-p
: Specifies the local paths that the projects are inside. You can use|
character to separate the paths.
Example:
abp switch-to-local --paths "D:\Github\abp|D:\Github\my-repo"
translate
Simplifies to translate localization files when you have multiple JSON localization files in a source control repository.
- This command will create a unified json file based on the reference culture.
- It searches all the localization
JSON
files in the current directory and all subdirectories (recursively). Then creates a single file (namedabp-translation.json
by default) that includes all the entries need to be translated. - Once you translate the entries in this file, you can then apply your changes to the original localization files using the
--apply
command.
The main purpose of this command is to translate ABP Framework localization files (since the abp repository has tens of localization files to be translated in different directories).
Creating the Translation File
First step is to create the unified translation file:
abp translate -c <culture> [options]
Example:
abp translate -c de
This command created the unified translation file for the de
(German) culture.
Additional Options
--reference-culture
or-r
: Defaulten
. Specifies the reference culture.--output
or-o
: Output file name. Defaultabp-translation.json
.--all-values
or-all
: Include all keys to translate. By default, the unified translation file only includes the missing texts for the target culture. Specify this parameter if you may need to revise the values already translated before.
Applying Changes
Once you translate the entries in the unified translation file, you can apply your changes to the original localization files using the --apply
parameter:
abp translate --apply # apply all changes
abp translate -a # shortcut for --apply
Then review changes on your source control system to be sure that it has changed the proper files and send a Pull Request if you've translated ABP Framework resources. Thank you in advance for your contribution.
Additional Options
--file
or-f
: Default:abp-translation.json
. The translation file (use only if you've used the--output
option before).
Online DeepL translate
The translate
command also supports online translation. You need to provide your DeepL Authentication Key.
It will search all the en.json(reference-culture)
files in the directory and sub-directory and then translate and generate the corresponding zh-Hans.json(culture)
files.
abp translate -c zh-Hans --online --deepl-auth-key <auth-key>
login
Some features of the CLI requires to be logged in to abp.io platform. To login with your username write:
abp login <username> # Allows you to enter your password hidden
abp login <username> -p <password> # Specify the password as a parameter (password is visible)
abp login <username> --organization <organization> # If you have multiple organizations, you need set your active organization
abp login <username> -p <password> -o <organization> # You can enter both your password and organization in the same command
abp login <username> --device # Use device login flow
When using the -p parameter, be careful as your password will be visible. It's useful for CI/CD automation pipelines.
A new login with an already active session overwrites the previous session.
login-info
Shows your login information such as Name, Surname, Username, Email Address and Organization.
abp login-info
logout
Logs you out by removing the session token from your computer.
abp logout
bundle
This command generates script and style references for ABP Blazor WebAssembly and MAUI Blazor project and updates the index.html file. It helps developers to manage dependencies required by ABP modules easily. In order bundle
command to work, its executing directory or passed --working-directory
parameter's directory must contain a Blazor or MAUI Blazor project file(*.csproj).
Usage:
abp bundle [options]
Options
--working-directory
or-wd
: Specifies the working directory. This option is useful when executing directory doesn't contain a Blazor project file.--force
or-f
: Forces to build project before generating references.--project-type
or-t
: Specifies the project type. Default type iswebassembly
. Available types:webassembly
maui-blazor
bundle
command reads the appsettings.json
file inside the Blazor and MAUI Blazor project for bundling options. For more details about managing style and script references in Blazor or MAUI Blazor apps, see Managing Global Scripts & Styles
install-libs
This command install NPM Packages for MVC / Razor Pages and Blazor Server UI types. Its executing directory or passed --working-directory
parameter's directory must contain a project file(*.csproj).
install-libs
command reads the abp.resourcemapping.js
file to manage package. For more details see Client Side Package Management.
Usage:
abp install-libs [options]
Options
--working-directory
or-wd
: Specifies the working directory. This option is useful when executing directory doesn't contain a project file.