# Get started

> Create your first budget with the OpenStack CLI, so that Budgets emails you when a project has spent 80% of its monthly amount.

This page takes you from nothing to a monthly budget that emails you when your project has spent
80% of it. It takes about five minutes, most of which is waiting for a confirmation email.

## Before you begin

You need:

* The `openstack` CLI, signed in to the project you want to watch. [Set up the CLI](/developer/cli)
  if you have not already.
* An email address you can read.

## 1. Install the Budgets commands

```sh
pip install vexxhost-budgetclient
```

## 2. Create an email channel

A notification channel is where alerts go. Create one for your email address:

```sh
openstack budget channel create finance --type email --address finance@example.com
```

```
+------------+--------------------------------------+
| Field      | Value                                |
+------------+--------------------------------------+
| id         | 3f9c1e7a-2b4d-4c6e-8a1f-5d7b9e2c4a6f |
| name       | finance                              |
| project_id | a6f1c2d93b8e4f07b5d4e2c1a9f8e7d6     |
| type       | email                                |
| status     | pending_confirmation                 |
| url        | None                                 |
| address    | finance@example.com                  |
| created_by | 4c8e2f1a9b7d4e6f8a3c5b1d7e9f2a4c     |
| created_at | 2026-10-07T14:02:11Z                 |
+------------+--------------------------------------+
```

Budgets sends a confirmation message to the address. Open it, follow the link, and select
**Confirm**. Until you do, the channel stays `pending_confirmation` and receives no alerts.

## 3. Create the budget

Create a monthly budget of 1000 with one threshold at 80% of actual spending, sent to the
channel you created:

```sh
openstack budget create team-monthly \
  --amount 1000 \
  --period monthly \
  --threshold name=warn,value=80,channel=finance \
  -c id -c name -c amount -c currency -c period
```

```
+----------+--------------------------------------+
| Field    | Value                                |
+----------+--------------------------------------+
| id       | c7e1a5b3-9d2f-4e8c-a6b4-1f3d5e7c9a2b |
| name     | team-monthly                         |
| amount   | 1000                                 |
| currency | USD                                  |
| period   | monthly                              |
+----------+--------------------------------------+
```

The currency is the one your costs are reported in, so you do not set it.

## 4. Check the budget

Budgets checks each budget about once an hour. After the first check, `budget show` reports what
the project has spent this month:

```sh
openstack budget show team-monthly -c window -c actual_spend -c threshold_states
```

```
+------------------+---------------------------------------------------------------------------+
| Field            | Value                                                                     |
+------------------+---------------------------------------------------------------------------+
| window           | 2026-10-01T00:00:00Z - 2026-11-01T00:00:00Z                               |
| actual_spend     | 248.731250000000                                                          |
| threshold_states | name='warn', observed='248.731250000000', state='ok', target_amount='800' |
+------------------+---------------------------------------------------------------------------+
```

The `warn` threshold is `ok` while spending stays under 800. When it reaches 800, the state
changes to `alarm` and Budgets emails `finance@example.com`.

## Next steps

* Add a threshold that warns when the month is forecast to go over budget. See
  [Thresholds](/budgets/concepts/thresholds).
* Send alerts to chat or your own systems with a [webhook](/budgets/guides/receive-webhook-alerts).
* Learn how periods, spending and alerts fit together in [Budgets concepts](/budgets/concepts/budgets).