---
title: "Inbox CLI"
description: "A command-line inbox for the notifications of every forge you configure."
canonical_url: "https://docs-oquac2tli-poetry.vercel.app/examples/inbox-cli"
---
# Inbox CLI

> A command-line inbox for the notifications of every forge you configure.

`inbox-cli` prints one line per notification, newest first, from every forge you configure. [View the source](https://github.com/danielroe/forges/tree/main/examples/inbox-cli).

It reads providers from the `FORGES_<KIND>_<FIELD>` environment variables with [`providersFromEnv()`](https://docs-oquac2tli-poetry.vercel.app/guides/environment). Some providers can't list notifications, such as Bitbucket, Azure DevOps and Cursor Origin. For those providers, the CLI lists the open threads in the repository that you set in `FORGES_<KIND>_DEMO_REPO`. Provider warnings go to stderr.

## Run it

```sh
FORGES_GITHUB_TOKEN=ghp_... \
FORGES_BITBUCKET_USERNAME=me FORGES_BITBUCKET_PASSWORD=app-password \
FORGES_BITBUCKET_DEMO_REPO=acme/widgets \
pnpm --filter @forges-examples/inbox-cli start
```

```text
github:github.com:notification/901234567  2025-09-18 09:12  github  acme/widgets  pull_request  review_requested  Add retry handling to the uploader
```

The first column is the key of the row. To mark a notification done, pass its key to `--done`:

```sh
pnpm --filter @forges-examples/inbox-cli start -- --done \
github:github.com:notification/901234567
```

On a forge that has only a read state, `--done` marks the notification read.

## What it shows

- Loading providers with `providersFromEnv()` and reading the `skipped` reasons.
- Falling back from `notifications.list()` to `threads.list()` when `can()` says no.
- Using `notificationKey()` to give each row a stable ID.

## Run the tests

```sh
pnpm --filter @forges-examples/inbox-cli test
```

The tests run the real providers against fixtures, without a network connection.


## Sitemap

See the full [sitemap](https://docs-oquac2tli-poetry.vercel.app/sitemap.md) for all pages.