# 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](https://docs.diagrid.io/develop/connect) 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](https://docs.diagrid.io/getting-started/quickstarts/workflow), [agent](https://docs.diagrid.io/develop/agents/dapr-agents/durable-agent-quickstart), or [microservice](https://docs.diagrid.io/getting-started/quickstarts/dapr-apis/invocation.mdx)—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 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:

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

Example:

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

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

```bash
diagrid dev run --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](https://docs.dapr.io/developing-applications/local-development/multi-app-dapr-run/multi-app-overview/) to manage multiple applications, `diagrid dev run` is compatible with this format. You can use your existing multi-app run file directly:

```bash
diagrid dev run -f my-apps.yaml
```

This command will:

- Connect to your Catalyst project (or create it if it doesn't exist)
- Create apps, components, and subscriptions as needed
- Launch all local applications
- Inject environment variables for Catalyst connectivity
- Establish tunnels for apps receiving outbound requests

<details>
  <summary>How-to: Generate a Multi-App File from existing Catalyst Resources</summary>

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

  ```bash
  diagrid dev scaffold
  ```

  This creates `<project-name>.yaml` with all apps, 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`.
</details>

### Manage local connections

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

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

Check active connections:

```bash
diagrid dev status
```

Stop a local connection:

```bash
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 in your project. Create if needed:

```bash
diagrid project create my-test-project
diagrid app 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 ->](https://docs.diagrid.io/references/catalyst/cli-reference/call)

### 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 ->](https://docs.diagrid.io/references/catalyst/cli-reference/listen)

## 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](https://docs.diagrid.io/develop/connect#configure-dapr-sdks-with-environment-variables) for the full set of values to retrieve and export.