Skip to main content

Connect via the Diagrid CLI for dev/test

Whether you have an application written with the Dapr SDKs, or you just want to test out a few capabilities, there are ways for you to try out the platform and get a feel for its capabilities and features. Building on the Connect to Catalyst guide, this page shows you how to connect to Catalyst from your local machine using the Diagrid CLI.

Prerequisites​

Before connecting locally, ensure you have the Diagrid CLI installed and authenticated (diagrid login)

Connect an existing Dapr application​

If you already have a Dapr application—whether it's a workflow, agent, or microservice—you can connect it to Catalyst with minimal changes. Your application code using Dapr SDKs will work as-is; you just need to point it to Catalyst's endpoints instead of a local Dapr sidecar.

Run a single application​

The diagrid dev run command is compatible with dapr run and connects your local application to Catalyst by:

  • Injecting environment variables (project endpoints and App ID API token) for Dapr SDKs
  • Creating a local application connection tunnel for outbound requests
  • Running your application with the proper configuration

For applications that only make requests to Catalyst APIs:

diagrid dev run --app-id my-app <your-startup-command>

Example:

diagrid dev run --app-id publisher "java -jar target/app.jar"

For applications that receive outbound requests (subscriptions, bindings, invocations), specify the local port:

diagrid dev run --app-id subscriber --app-port 9001 "java -jar target/app.jar --port=9001"

The CLI creates a tunnel from Catalyst to your local port, routing all traffic to your local application.

Run multiple applications with a multi-app file​

If you're using a Dapr multi-app run file to manage multiple applications, diagrid dev run is compatible with this format. You can use your existing multi-app run file directly:

diagrid dev run -f my-apps.yaml

This command will:

  • Connect to your Catalyst project (or create it if it doesn't exist)
  • Create App IDs, components, and subscriptions as needed
  • Launch all local applications
  • Inject environment variables for Catalyst connectivity
  • Establish tunnels for apps receiving outbound requests
How-to: Generate a Multi-App File from existing Catalyst Resources

If you have an existing Catalyst project with resources already configured, you can scaffold a multi-app run file:

diagrid dev scaffold

This creates <project-name>.yaml with all App IDs, components, and subscriptions from your project. Update the file with:

  • Local application directories (appDirPath)
  • Startup commands (command)
  • Local ports (appPort) for apps receiving requests

Then run it with diagrid dev run -f <project-name>.yaml.

Manage local connections​

Start a connection tunnel without running an app (useful for debugging):

diagrid dev run --app-id my-app --app-port 9001

Check active connections:

diagrid dev status

Stop a local connection:

diagrid dev stop -a my-app

Smoke testing via CLI​

If you don't have an application yet, you can quickly test Catalyst capabilities using the Diagrid CLI. This is useful for:

  • Validating component configurations
  • Testing subscriptions and bindings
  • Verifying infrastructure connectivity
  • Exploring Catalyst APIs

Prerequisites for testing​

You'll need a Project and at least one App ID in your project. Create if needed:

diagrid project create my-test-project
diagrid appid create my-test-app --project my-test-project

Making API calls​

Use diagrid call to invoke Catalyst APIs directly from the CLI. See diagrid call command reference ->

Receiving outbound requests​

Use diagrid listen to receive outbound requests from Catalyst (pub/sub messages, input bindings, service invocations) without deploying application code. See diagrid listen command reference ->

Manual Connection Details​

The diagrid dev run command injects connection details automatically. If you are using Dapr SDKs directly without diagrid dev run — for example, running your app from your IDE or against a remote endpoint — see Configure Dapr SDKs with environment variables for the full set of values to retrieve and export.

Last updated on