The Dapr CLI (Command Line Interface) is a tool designed to manage and develop applications built with Dapr, an open-source runtime for building cloud-native applications. It provides essential commands to initialize projects, run services, and interact with Dapr components.
Key Features:
Initialization: Quickly start new projects using the dapr init command.
Runtime Control: Run applications locally or in a Kubernetes cluster using dapr run.
Component Management: Interact with Dapr's built-in components (e.g., state stores, pub/sub) through commands like dapr components.
Audience & Benefit:
Ideal for developers building microservices and cloud-native applications. The Dapr CLI streamlines workflows by enabling quick setup, testing, and deployment of Dapr-based services, ultimately enhancing developer productivity.
The tool is available across platforms (Linux, macOS, Windows) and can be installed via winget or other package managers.
README
Dapr CLI
The Dapr CLI allows you to setup Dapr on your local dev machine or on a Kubernetes cluster, provides debugging support, launches and manages Dapr instances.
Getting started
Prerequisites
On default, during initialization the Dapr CLI will install the Dapr binaries as well as setup a developer environment to help you get started easily with Dapr. This environment uses Docker containers, therefore Docker needs to be installed. If you prefer to run Dapr without this environment and no dependency on Docker, after installation of the CLI make sure to follow the instructions to initialize Dapr using slim init.
Note, if you are a new user, it is strongly recommended to install Docker and use the regular init command.
>Note: On Windows, Docker must be running in Linux Containers mode
Installing Dapr CLI
Using script to install the latest release
Windows
Install the latest windows Dapr CLI to $Env:SystemDrive\dapr and add this directory to User PATH environment variable. Use -DaprRoot [path] to change the default installation directory
Unpack it (e.g. dapr_linux_amd64.tar.gz, dapr_windows_amd64.zip)
Move it to your desired location.
For Linux/MacOS - /usr/local/bin
For Windows, create a directory and add this to your System PATH. For example create a directory called c:\dapr and add this directory to your path, by editing your system environment variable.
> NOTE: The default installation directory is set to $Env:SystemDrive\dapr and can be modified at the time of installation.
Install Dapr on your local machine (self-hosted)
In self-hosted mode, dapr can be initialized using the CLI with the placement, scheduler, redis, and zipkin containers enabled by default(recommended) or without them which also does not require docker to be available in the environment.
Initialize Dapr
(Prerequisite: Docker is available in the environment - recommended)
Use the init command to initialize Dapr. On init, multiple default configuration files and containers are installed along with the dapr runtime binary. Dapr runtime binary is installed under $HOME/.dapr/bin for Mac, Linux and %USERPROFILE%.dapr\bin for Windows.
dapr init
> For Linux users, if you run your docker cmds with sudo, you need to use "sudo dapr init"
Output should look like so:
⌛ Making the jump to hyperspace...
✅ Downloaded binaries and completed components set up.
ℹ️ daprd binary has been installed to $HOME/.dapr/bin.
ℹ️ dapr_placement container is running.
ℹ️ dapr_scheduler container is running.
ℹ️ dapr_redis container is running.
ℹ️ dapr_zipkin container is running.
ℹ️ Use `docker ps` to check running containers.
✅ Success! Dapr is up and running. To get started, go here: https://docs.dapr.io/getting-started
> Note: To see that Dapr has been installed successfully, from a command prompt run the docker ps command and check that the daprio/dapr:latest, dapr_redis and dapr_zipkin container images are all running.
This step creates the following defaults:
components folder which is later used during dapr run unless the --resources-path (--components-path is deprecated and will be removed in future releases) option is provided. For Linux/MacOS, the default components folder path is $HOME/.dapr/components and for Windows it is %USERPROFILE%\.dapr\components.
component files in the components folder called pubsub.yaml and statestore.yaml.
default config file $HOME/.dapr/config.yaml for Linux/MacOS or for Windows at %USERPROFILE%\.dapr\config.yaml to enable tracing on dapr init call. Can be overridden with the --config flag on dapr run.
Slim Init
Alternatively to the above, to have the CLI not install any default configuration files or run Docker containers, use the --slim flag with the init command. Only Dapr binaries will be installed.
dapr init --slim
Output should look like so:
⌛ Making the jump to hyperspace...
✅ Downloaded binaries and completed components set up.
ℹ️ daprd binary has been installed to $HOME/.dapr/bin.
ℹ️ placement binary has been installed.
ℹ️ scheduler binary has been installed.
✅ Success! Dapr is up and running. To get started, go here: https://docs.dapr.io/getting-started
>Note: When initializing Dapr with the --slim flag only the Dapr runtime, placement, and scheduler service binaries are installed. An empty default components folder is created with no default configuration files. During dapr run user should use --resources-path (--components-path is deprecated and will be removed in future releases) to point to a components directory with custom configurations files or alternatively place these files in the default directory. For Linux/MacOS, the default components directory path is $HOME/.dapr/components and for Windows it is %USERPROFILE%\.dapr\components.
Install a specific runtime version
You can install or upgrade to a specific version of the Dapr runtime using dapr init --runtime-version. You can find the list of versions in Dapr Release.
# Install v1.0.0 runtime
dapr init --runtime-version 1.0.0
# Check the versions of CLI and runtime
dapr --version
CLI version: v1.0.0
Runtime version: v1.0.0
Install with mariner images
You can install Dapr Runtime using mariner images using the --image-variant flag.
# Installing Dapr with Mariner images
dapr init --image-variant mariner
Install by providing a docker container registry url
You can install Dapr runtime by pulling docker images from a given private registry uri by using --image-registry flag.
> Note: This command expects that images have been hosted like example.io//dapr/dapr:, example.io//dapr/3rdparty/redis:, example.io//dapr/3rdparty/zipkin:
# Example of pulling images from a private registry.
dapr init --image-registry example.io/
Install with a custom scheduler host and port
You can install Dapr runtime with a custom scheduler host and port by using --scheduler-override-broadcast-host-port flag.
You can install Dapr runtime in airgap (offline) environment using a pre-downloaded installer bundle. You need to download the archived bundle for your OS beforehand (e.g., daprbundle_linux_amd64.tar.gz,) and unpack it. Thereafter use the local Dapr CLI binary in the bundle with --from-dir flag in the init command to point to the extracted bundle location to initialize Dapr.
Move to the bundle directory and run the following command:
# Initializing dapr in airgap environment
./dapr init --from-dir .
> For windows, use .\dapr.exe to point to the local Dapr CLI binary.
> If you are not running the above command from the bundle directory, provide the full path to bundle directory as input. For example, assuming the bundle directory path is $HOME/daprbundle, run $HOME/daprbundle/dapr init --from-dir $HOME/daprbundle to have the same behavior.
> Note: Dapr Installer bundle just contains the placement and scheduler containers apart from the binaries and so zipkin and redis are not enabled by default. You can pull the images locally either from network or private registry and run as follows:
docker run --name "dapr_zipkin" --restart always -d -p 9411:9411 openzipkin/zipkin
docker run --name "dapr_redis" --restart always -d -p 6379:6379 redis
Alternatively to the above, you can also have slim installation as well to install dapr without running any Docker containers in airgap mode.
./dapr init --slim --from-dir .
Install to a specific Docker network
You can install the Dapr runtime to a specific Docker network in order to isolate it from the local machine (e.g. to use Dapr from within a Docker container).
# Create Docker network
docker network create dapr-network
# Install Dapr to the network
dapr init --network dapr-network
> Note: When installed to a specific Docker network, you will need to add the --placement-host-address arguments to dapr run commands run in any containers within that network.
> The format of --placement-host-address argument is either `` or :. If the port is omitted, the default port 6050 for Windows and 50005 for Linux/MacOS applies.
> Note: When installed to a specific Docker network, you will need to add the --scheduler-host-address arguments to dapr run commands run in any containers within that network.
> The format of --scheduler-host-address argument is either `` or :. If the port is omitted, the default port 6060 for Windows and 50006 for Linux/MacOS applies.
Install with a specific container runtime
You can install the Dapr runtime using a specific container runtime
environment such as Docker or Podman by passing along the
--container-runtime argument:
# Install Dapr with Podman
$ dapr init --container-runtime podman
> Note: The default container runtime is Docker.
In a dev container or GitHub Codespace
To install the Dapr CLI in a dev container or GitHub Codespace, add the following to your devcontainer.json file:
"features": {
"ghcr.io/dapr/cli/dapr-cli:0": {}
}
Restart your dev container or GitHub Codespace and run dapr init to initialize Dapr.
Uninstalling will remove daprd binary along with the placement and scheduler containers (if installed with Docker or the placement and scheduler binaries if not).
dapr uninstall
> For Linux users, if you run your docker cmds with sudo, you need to use "sudo dapr uninstall" to remove the containers.
The command above won't remove the redis or zipkin containers by default in case you were using it for other purposes. It will also not remove the default dapr folder that was created on dapr init. To remove all the containers (placement, scheduler, redis, zipkin) and also the default dapr folder created on init run:
dapr uninstall --all
The above command can also be run when Dapr has been installed in a non-docker environment, it will only remove the installed binaries and the default dapr folder in that case.
> NB: The dapr uninstall command will always try to remove the placement and scheduler binaries/services and will throw an error is not able to.
You should always run a dapr uninstall before running another dapr init.
Uninstall Dapr from a specific Docker network
If previously installed to a specific Docker network, Dapr can be uninstalled with the --network argument:
dapr uninstall --network dapr-network
Uninstall Dapr from a specific container runtime
You can uninstall Dapr from a specific container runtime
environment by passing along the --container-runtime argument:
The init command will install Dapr to a Kubernetes cluster. For more advanced use cases, use our Helm Chart.
Note: The default namespace is dapr-system. The installation will appear under the name dapr for Helm
dapr init -k
Output should look like as follows:
⌛ Making the jump to hyperspace...
ℹ️ Note: To install Dapr using Helm, see here: https://docs.dapr.io/getting-started/install-dapr/#install-with-helm-advanced
✅ Deploying the Dapr control plane to your cluster...
✅ Success! Dapr has been installed to namespace dapr-system. To verify, run "dapr status -k" in your terminal. To get started, go here: https://docs.dapr.io/getting-started
> Note: When in a specific Docker network, the Redis, Zipkin and placement and scheduler service containers are given specific network aliases, dapr_redis, dapr_zipkin, dapr_placement, and dapr_scheduler, respectively. The default configuration files reflect the network alias rather than localhost when a docker network is specified.
Use gRPC
If your app uses gRPC instead of HTTP to receive Dapr events, run the CLI with the following command:
dapr run --app-id nodeapp --app-protocol grpc --app-port 6000 node app.js
The example above assumed your app port is 6000.
Publish/Subscribe
To use pub-sub with your app, make sure that your app has a POST HTTP endpoint with some name, say myevent.
This sample assumes your app is listening on port 3000.
Launch Dapr and your app:
dapr run --app-id nodeapp --app-port 3000 node app.js
Publish a message:
The --pubsub parameter takes in the name of the pub/sub. The default name of the pub/sub configed by the CLI is "pubsub".
To test your endpoints with Dapr, simply expose any HTTP endpoint.
For this sample, we'll assume a node app listening on port 3000 with a /mymethod endpoint.
Launch Dapr and your app:
dapr run --app-id nodeapp --app-port 3000 node app.js
Note: To choose a non-default components folder, use the --resources-path(--components-path is deprecated) option.
Invoke your app:
dapr invoke --app-id nodeapp --method mymethod
Specify a verb:
By default, Dapr will use the POST verb. If your app uses Dapr for gRPC, you should use POST.
dapr invoke --app-id nodeapp --method mymethod --verb GET
List
To list all Dapr instances running on your machine:
dapr list
To list all Dapr instances running in a Kubernetes cluster:
dapr list --kubernetes
To list all Dapr instances but return output as JSON or YAML (e.g. for consumption by other tools):
dapr list --output json
dapr list --output yaml
Check system services (control plane) status
Check Dapr's system services (control plane) health status in a Kubernetes cluster:
dapr status --kubernetes
Check mTLS status
To check if Mutual TLS is enabled in your Kubernetes cluster:
dapr mtls --kubernetes
Export TLS certificates
To export the root cert, issuer cert and issuer key created by Dapr from a Kubernetes cluster to a local path:
dapr mtls export
This will save the certs to the working directory.
To specify a custom directory:
dapr mtls export -o certs
Check root certificate expiry
dapr mtls expiry
This can be used when upgrading to a newer version of Dapr, as it's recommended to carry over the existing certs for a zero downtime upgrade.
Renew Dapr certificates of a kubernetes cluster with one of the 3 ways mentioned below:
Renew certificate by generating new root and issuer certificates
In order to set the Dapr runtime to log API calls with INFO log verbosity, use the enable-api-logging flag:
dapr run --app-id nodeapp --app-port 3000 node app.js enable-api-logging
The default is false.
For more details, please run the command and check the examples to apply to your shell.
Apply Dapr annotations
To add or modify dapr annotations on an existing Kubernetes manifest, use the dapr annotate command:
dapr annotate [flags] mydeployment.yaml
This will add the dapr.io/enabled and the dapr.io/app-id annotations. The dapr app id will be genereated using the format -- where the values are taken from the existing Kubernetes object metadata.
> NOTE: The annotate command currently only supports annotating Kubernetes manifests. You must provide the -k flag to target Kubernetes.
To provide your own dapr app id, provide the flag --app-id.
All dapr annotations are available to set if a value is provided for the appropriate flag on the dapr annotate command.
You can also provide the Kubernetes manifest via stdin:
If the input contains multiple manifests then the command will search for the first appropriate one to apply the annotations. If you'd rather it applied to a specific manifest then you can provide the --resource flag with the value set to the name of the object you'd like to apply the annotations to. If you have a conflict between namespaces you can also provide the namespace via the --namespace flag to isolate the manifest you wish to target.
If you want to annotate multiple manifests, you can chain together the dapr annotate commands with each applying the annotation to a specific manifest.
