# Diagrid CLI for Catalyst

The Diagrid CLI allows you to manage and interact with your Catalyst resources. The CLI can perform most actions available in the Catalyst Console and provides additional utilities you can use to develop your applications using the APIs. For example, use the Diagrid CLI to:

- Create and manage apps, agents, MCP servers, components, subscriptions,...
- Invoke the Catalyst APIs and listen for incoming requests on a given app
- Connect Catalyst to your local machine to receive pubsub events, service invocations, input bindings, etc. while developing
- View app logs

## Installing the CLI

Once you have created your Diagrid Catalyst account, you can access your organization at [https://catalyst.diagrid.io](https://diagrid.ws/get-catalyst).

Next, download and install the Diagrid CLI using the following command:

**MacOS**

```bash
curl -o- https://downloads.diagrid.io/cli/install.sh | bash
```

Move the `diagrid` binary into your path so you can run it from anywhere. For example:

```bash
sudo mv ./diagrid /usr/local/bin
```

**Linux**

```bash
curl -o- https://downloads.diagrid.io/cli/install.sh | bash
```

Move the `diagrid` binary into your path so you can run it from anywhere. For example:

```bash
sudo mv ./diagrid /usr/local/bin
```

**Windows**

Download the PowerShell installer

```shell
iwr -Uri https://downloads.diagrid.io/cli/install.ps1 -OutFile install.ps1
```

Execute the PowerShell installer

```
.\install.ps1
```

:::tip
You may need to temporarily set the PowerShell execution policy to `Unrestricted` to allow the installer to execute.

```shell
Set-ExecutionPolicy Unrestricted -Scope CurrentUser

.\install.ps1

Set-ExecutionPolicy Restricted -Scope CurrentUser
```

:::

Move the `diagrid.exe` executable into your path so you can run it from anywhere. For example:

```shell
Move-Item .\diagrid.exe "$($env:USERPROFILE)\bin"
```

:::warning

Support for the Diagrid CLI on Windows is experimental and we recommend installing it via [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) if available. The CLI on WSL2 requires https://wslutiliti.es/wslu/ to support deeper OS integration.

:::

## Using the CLI

The CLI is a static binary that should be executed from the command line. Help pages are available for you to navigate the command tree and see what flags are available on each command.

To login to Diagrid Catalyst:

```bash
diagrid login
```

The Diagrid CLI is compatible with both products: Catalyst and Dapr Ops Dashboard. If you have access to both products, you can choose which set of commands to use by specifying the product name with the command:

```
diagrid product use catalyst
```

To verify the current user identity and organization:

```bash
diagrid whoami
```

To clean up your user data, use the logout command:

```bash
diagrid logout
```

## Creating your first project

In order to begin using the Catalyst APIs, you must first create a project. After creating the project, you can begin creating workloads and components.

```bash
# Create project with Diagrid infrastructure resources and managed workflows
diagrid project create myproject --deploy-managed-pubsub --deploy-managed-kv --enable-managed-workflow

# Create an appid
diagrid app create my-appid

# Create a subscription to the Diagrid Pub/Sub Broker
diagrid subscription create my-subscription --component pubsub --topic events --route /events --scopes my-appid

# View all resources for the current project and wait until all resources become ready
diagrid project get -a

# Connect a terminal to the App ID and listen for incoming subscription events
diagrid listen --id my-appid --subscription my-subscription
```

Now in a different terminal:

```bash
# Publish a message to the pub/sub broker on the events topic and observe output in the listening terminal
diagrid call publish events --component pubsub --id my-appid --data "hello world"
```

## Other useful commands

List all projects in an organization:

```bash
diagrid project list
```

Set the default project for all subsequent commands:

```bash
diagrid project use my-project
```

View all resources in a project:

```bash
diagrid project get -a
```