Griffin CLI

Command-line interface for running and managing Griffin API monitors. Supports local execution, validation, syncing to the hub, and managing environments, variables, secrets, integrations, and notifications.

Overview

Griffin CLI provides monitoring-as-code with:

1. Local development: Write monitors in TypeScript/JavaScript under __griffin__/ directories; validate and run them locally with griffin validate and griffin test.
2. Hub sync: Preview changes with griffin plan, apply with griffin apply, or remove with griffin destroy.
3. Hub operations: List runs, trigger runs, and view metrics with griffin runs, griffin run, and griffin metrics.
4. Configuration: Manage environments, variables (in state), and secrets (on hub) per environment; manage integrations and notification rules.

Installation

npm install -g @griffin-app/griffin-cli

Or run via npx:

npx @griffin-app/griffin-cli <command>

The CLI is also available as the gr binary.

Quick Start

1. Initialize

griffin init
griffin init --project my-service   # override project ID

Creates .griffin/state.json with project ID, default environment, and hub config. Add .griffin/ to .gitignore if you keep local-only state there.

2. Optional: environments and variables

griffin env add staging
griffin env add production
griffin variables add API_BASE=https://staging.example.com --env staging
griffin variables add API_BASE=https://api.example.com --env production

Variables are stored in .griffin/state.json per environment and used when running monitors (e.g. for variable("API_BASE") in the monitor DSL).

3. Create monitors

Add TypeScript or JavaScript files under __griffin__/ directories. Each file should export a default monitor (DSL). Discovery uses **/__griffin__/*.{ts,js} by default (configurable in state under discovery).

4. Validate and run locally

griffin validate
griffin test
griffin test --env staging

griffin test runs discovered monitors locally using variables from state for the given environment.

5. Connect to the hub (optional)

• Griffin Cloud: griffin auth login (device flow; token stored in ~/.griffin/credentials.json).
• Self-hosted: griffin auth connect --url https://hub.example.com --token <api-key>.

6. Preview and apply to hub

griffin plan
griffin plan --env production --json
griffin apply --env production
griffin apply --env production --auto-approve
griffin apply --env production --dry-run
griffin apply --env production --prune   # delete hub monitors not present locally

7. Runs and metrics

griffin runs
griffin runs --env production --monitor health-check --limit 20
griffin run --env production --monitor health-check
griffin run --env production --monitor health-check --wait
griffin metrics --env production
griffin metrics --env production --period 7d --json

Commands

Commands are top-level or under a group. The default environment is default unless overridden with --env <name> where supported.

| Area | Commands | Purpose | | ----------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | Project | init, validate, status | Bootstrap, validate monitors, show status | | Local run | test | Run monitors locally | | Hub sync | plan, apply, destroy | Preview changes, push to hub, remove from hub | | Hub runs | runs, run, metrics | List runs, trigger run, view metrics | | Auth | auth login, auth logout, auth connect, auth generate-key | Cloud or self-hosted auth | | Environments | env list, env add, env remove | Manage environments | | Variables | variables list, variables add, variables remove | Per-environment variables (in state) | | Secrets | secrets list, secrets set, secrets get, secrets delete | Per-environment secrets (stored on hub) | | Integrations | integrations list, integrations show, integrations connect, integrations update, integrations remove | Slack, email, webhooks, etc. | | Notifications | notifications list, notifications test | Notification rules and test sends |

Top-level commands

• griffin init – Initialize Griffin in the current directory. Options: --project <name>.
• griffin validate – Check monitor files for errors (no run, no hub).
• griffin status – Show project and hub connection status.
• griffin test – Run monitors locally. Options: --env <name> (default: default).
• griffin plan – Preview pending monitor changes. Options: --env <name>, --json. Exit code 2 if there are changes.
• griffin apply – Push monitor changes to the hub. Options: --env <name>, --auto-approve, --dry-run, --prune.
• griffin destroy – Destroy monitors on the hub. Options: --env <name>, --monitor <nameOrId>, --auto-approve, --dry-run.
• griffin runs – List recent runs. Options: --env <name>, --monitor <name>, --limit <number>.
• griffin run – Trigger a monitor run. Options: --env <name>, --monitor <name> (required), --wait, --force.
• griffin metrics – Show metrics summary. Options: --env <name>, --period <1h|6h|24h|7d|30d>, --json.

Auth (griffin auth)

• auth login – Authenticate with Griffin Cloud (device flow).
• auth logout – Clear stored credentials.
• auth connect – Set hub URL and API key for self-hosted. Requires --url <url> and --token <token>.
• auth generate-key – Generate an API key.

Environments (griffin env)

• env list – List configured environments.
• env add <name> – Add an environment.
• env remove <name> – Remove an environment.

Variables (griffin variables)

Variables live in .griffin/state.json per environment (not in a separate file). Use them in monitors via variable("KEY").

• variables list – List variables. Option: --env <name>.
• variables add <KEY=VALUE> – Set a variable. Option: --env <name>.
• variables remove <key> – Remove a variable. Option: --env <name>.

Secrets (griffin secrets)

Secrets are stored on the hub per environment. Use them in monitors via secret("REF").

• secrets list – List secret names. Options: --env <name>, --json.
• secrets set <name> – Create or update a secret. Options: --env <name>, --value <value> (avoid for sensitive data).
• secrets get <name> – Show secret metadata. Options: --env <name>, --json.
• secrets delete <name> – Delete a secret. Options: --env <name>, --force.

Integrations (griffin integrations)

• integrations list – List integrations. Options: --category, --provider, --env, --enabled, --json.
• integrations show <id> – Show integration details. Option: --json.
• integrations connect [type] [provider] – Connect a new integration. Options: --name, --env, --json.
• integrations update <id> – Update an integration. Options: --name, --env, --enabled, --json.
• integrations remove <id> – Remove an integration. Option: --force.

Notifications (griffin notifications)

• notifications list – List notification rules. Options: --monitor <id>, --enabled, --json.
• notifications test – Send a test notification. Options: --integration <id|name>, --channel, --to-addresses.

Configuration

Environment variable

• GRIFFIN_ENV – Default environment for commands (if the CLI respects it; otherwise pass --env explicitly).

State file (.griffin/state.json)

Stores project configuration:

• projectId – Project identifier.
• environments – Map of environment name to config (each can have optional variables).
• hub – baseUrl, optional clientId.
• cloud – authUrl (for Cloud login).
• discovery – Optional pattern (default **/__griffin__/*.{ts,js}) and ignore (e.g. ["node_modules/**", "dist/**"]).

Add .griffin/ to .gitignore if the file contains local-only overrides.

Credentials (~/.griffin/credentials.json)

User-level auth. Used by auth login and auth connect --token. Do not commit. Created with restricted permissions (0600).

Checklist

First-time setup

• Run griffin init (optionally griffin env add for extra environments).
• Add variables with griffin variables add KEY=value --env <env> for monitor variable("...") refs.
• Use griffin auth login or griffin auth connect for plan/apply/runs/run/metrics.

Before deploying

• griffin validate then griffin test --env <env>.
• griffin plan --env <env> then griffin apply --env <env> (use --dry-run or --auto-approve as needed).

Secrets in monitors

• Create/update with griffin secrets set REF --env <env>; ensure ref names match the monitor DSL (e.g. API_TOKEN).

Development

npm install
npm run build
npm run dev -- <command>   # e.g. npm run dev -- validate
npm run test

License

MIT