# Quickstart: State Management

In this quickstart, you'll run a stateful order application on [Catalyst Cloud](https://docs.diagrid.io/operate/hosting/catalyst-cloud). You will learn how to:

- Provision a Catalyst project with a managed KV store using the Diagrid CLI.
- Save and retrieve state items using the Dapr State API.
- Inspect stored data in the Catalyst web console.

```mermaid
---
title: Order App connected to Catalyst with KV Store
---
flowchart LR
  APP(Order App)
  subgraph Catalyst
    APPID(ID: order-app)
    STATE[(KV Store)]
  end

  APP<-->APPID
  APPID<-->STATE
```

## 1. Prerequisites

Before you proceed, ensure you have the following prerequisites installed.

**Python**

- [Diagrid Catalyst account](https://catalyst.diagrid.io/)
- [Diagrid CLI](https://docs.diagrid.io/getting-started/install-cli)
- [Git](https://git-scm.com/downloads)
- [Python 3.12+](https://www.python.org/downloads/) & [uv](https://docs.astral.sh/uv/#installation)

**.NET**

- [Diagrid Catalyst account](https://catalyst.diagrid.io/)
- [Diagrid CLI](https://docs.diagrid.io/getting-started/install-cli)
- [Git](https://git-scm.com/downloads)
- [.NET 10.0](https://dotnet.microsoft.com/en-us/download)

**JavaScript**

- [Diagrid Catalyst account](https://catalyst.diagrid.io/)
- [Diagrid CLI](https://docs.diagrid.io/getting-started/install-cli)
- [Git](https://git-scm.com/downloads)
- [Node.JS LTS](https://nodejs.org/en/)

**Java**

- [Diagrid Catalyst account](https://catalyst.diagrid.io/)
- [Diagrid CLI](https://docs.diagrid.io/getting-started/install-cli)
- [Git](https://git-scm.com/downloads)
- Java 17+: [OracleJDK](https://www.oracle.com/java/technologies/downloads/) or [OpenJDK](https://jdk.java.net/)
- [Apache Maven 3.9.5+](https://maven.apache.org/download.cgi)

## 2. Log in to Catalyst

Authenticate to Diagrid Catalyst using the following command:

```bash
diagrid login
```

This command opens a new browser window where you'll be shown a confirmation code that should match the code in your terminal.
Confirm the code, and if you're not logged into Catalyst, you'll be redirected to login.

Confirm your user details are correct using the following command:

```bash
diagrid whoami
```

The expected output contains the name of the organization, your user name, and the Catalyst API endpoint.

## 3. Clone Quickstart Code

Clone the quickstart code from GitHub:

```bash
git clone https://github.com/diagridio/catalyst-quickstarts
```

Navigate to the quickstart directory:

**Python**

**macOS/Linux**

```bash
cd catalyst-quickstarts/state/python
```

**Windows**

```powershell
cd catalyst-quickstarts\state\python
```

**.NET**

**macOS/Linux**

```bash
cd catalyst-quickstarts/state/csharp
```

**Windows**

```powershell
cd catalyst-quickstarts\state\csharp
```

**JavaScript**

**macOS/Linux**

```bash
cd catalyst-quickstarts/state/javascript
```

**Windows**

```powershell
cd catalyst-quickstarts\state\javascript
```

**Java**

**macOS/Linux**

```bash
cd catalyst-quickstarts/state/java
```

**Windows**

```powershell
cd catalyst-quickstarts\state\java
```

## 4. Install Dependencies

Install the dependencies for the state management application.

**Python**

Install Python dependencies:

```bash
uv sync --all-packages
```

**.NET**

Install .NET dependencies:

```bash
dotnet restore
```

**JavaScript**

Install Node dependencies:

```bash
npm install
```

**Java**

Install Maven dependencies:

```bash
mvn clean install
```

## 5. Run the application with Catalyst Cloud

The `diagrid dev run` command creates your Catalyst project, provisions resources (apps, Diagrid KV Store service), configures environment variables, and launches your application connected to Catalyst Cloud.

**Python**

```bash
uv run diagrid dev run -f state-quickstart.yaml --project state-quickstart --approve
```

**.NET**

```bash
diagrid dev run -f state-quickstart.yaml --project state-quickstart --approve
```

**JavaScript**

```bash
diagrid dev run -f state-quickstart.yaml --project state-quickstart --approve
```

**Java**

```bash
diagrid dev run -f state-quickstart.yaml --project state-quickstart --approve
```

:::tip
Wait a few seconds until you see application logs in the terminal to ensure the application is up and running and connected to Catalyst.
:::

## 6. Call the State API

With the quickstart running, test the State API by storing, retrieving, and deleting state items.

### 6.1 Store state

Open a new terminal and execute the following command to save a state item to the Diagrid KV store:

**macOS/Linux**

```bash
curl -i -X POST http://localhost:5001/order -H "Content-Type: application/json" -d '{"orderId":1}'
```

**Windows**

```powershell
Invoke-RestMethod -Method Post -Uri "http://localhost:5001/order" -ContentType "application/json" -Body '{"orderId":1}'
```

The expected response is:

```text
HTTP/1.1 200 OK
```

The application logs in the `diagrid dev run` terminal should show an order was saved.

### 6.2 Retrieve state

Confirm the state item was saved successfully by retrieving it:

**macOS/Linux**

```bash
curl -i -X GET http://localhost:5001/order/1
```

**Windows**

```powershell
Invoke-RestMethod -Method Get -Uri "http://localhost:5001/order/1"
```

The expected response body is:

```json
{"orderId":1}
```

### 6.3 View in the Catalyst web console

Open the [Catalyst Cloud web console](https://catalyst.r1.diagrid.io/kv-store/kvstore) and navigate to the KV Store data explorer to (Resources > Managed KV store) view stored state items.
The data explorer displays the key-value pairs saved by your application.

![Catalyst KV Store data explorer showing stored state items](https://docs.diagrid.io/img/catalyst/state-qs-datastore.png)

## 7. Clean Up

Press CTRL+C in the terminal that runs `diagrid dev run` to stop the application and disconnect from Catalyst Cloud.

To delete the entire project and all provisioned resources:

```bash
diagrid project delete state-quickstart
```

## Summary

In this quickstart you:

- Logged in to Catalyst and provisioned a managed state store project with a single CLI command (`diagrid dev run`).
- Saved and retrieved state items using the Dapr State API.
- Inspected stored data using the Catalyst KV Store data explorer.

Catalyst handled state persistence and key-value storage automatically — no infrastructure to manage.

## Next steps

- Explore the [Dapr API SDK guides](https://docs.diagrid.io/develop/dapr-apis) to integrate state management into your own applications.
- Try the [Pub/Sub quickstart](https://docs.diagrid.io/getting-started/quickstarts/dapr-apis/pubsub) to add event-driven messaging to your application.