---
title: Trigv CLI
description: Install and use the official Trigv CLI for shell scripts, cron jobs, CI pipelines, deploy hooks, and terminals.
---
# Trigv CLI

Use the official Trigv CLI to send push notifications from your terminal, shell scripts, cron jobs, CI pipelines, and deploy hooks.

## Install

```
npm install -g @trigv/cli
```

Or run without installing:

```
npx @trigv/cli send --channel general --title "Hello"
```

## Send a notification

```
export TRIGV_API_KEY="trgv_your_api_key"

trigv send \
		--channel general \
		--title "Deploy finished" \
		--description "Production is live" \
		--level success
```

## Command flags

| Flag | Required | Description |
| --- | :---: | --- |
| `--channel` | Yes | Channel slug, such as `general`, `deploys`, or `payments`. |
| `--title` | Yes | Push notification title. |
| `--description` | No | Body text shown in the notification. |
| `--image-url` | No | HTTPS image URL for screenshots, charts, camera snapshots, or previews. |
| `--url` | No | Destination URL opened from the notification. |
| `--level` | No | `info`, `success`, `warning`, or `error`. Defaults to `info`. |
| `--delivery-urgency` | No | `standard` or `time_sensitive`. Defaults to `standard`. |
| `--event-type` | No | Free-form event label such as `deploy.completed` or `cron.failed`. |
| `--idempotency-key` | No | Deduplication key for safe retries. |
| `--json` | No | Print machine-readable JSON output. |

## Safe retries with idempotency

```
trigv send \
		--channel deploys \
		--title "Production deploy complete" \
		--level success \
		--idempotency-key deploy-prod-42
```

Retries with the same key return the existing event instead of billing and sending another alert.

## Authentication and config

The CLI looks for credentials in this order:

1. `TRIGV_API_KEY` environment variable
2. macOS Keychain, when available
3. `~/.config/trigv/credentials`

Store a key interactively:

```
trigv config set-key
```

Verify the key:

```
trigv connection
```

Use `--base-url` only for local development or custom API environments.

## JSON output

Use `--json` when another script needs to read the result.

```
trigv send --channel general --title "Hello" --json
```

Successful responses include `ok`, `event`, and `duplicate`. Error responses include `ok: false`, `error`, `code`, and `status_code`.

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success. |
| `1` | Validation or usage error. |
| `2` | Missing API key or config. |
| `3` | API or network error. |

## Good places to use it

- CI/CD pipelines and deploy scripts
- Local shell scripts and scheduled jobs
- Any workflow where adding a single terminal command is easier than writing code

<DocsResourceLinks
  packageHref="https://www.npmjs.com/package/@trigv/cli"
  packageTitle="NPM package"
  packageDescription="Install the official Trigv CLI from npm."
  packageLabel="npm"
  sourceHref="https://github.com/Trigv/trigv-cli"
  sourceDescription="View the Trigv CLI source on GitHub."
/>