@griffin-app/griffin-cli 1.0.25 → 1.0.28

package/README.md

@@ -1,457 +1,212 @@
 # Griffin CLI
 
-Command-line interface for managing API monitoring tests as code.
+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 enables monitoring-as-code with support for both local test execution and hub-based orchestration. It provides a declarative workflow:
+Griffin CLI provides monitoring-as-code with:
 
-1. Write test monitors in TypeScript/JavaScript
-2. Run tests locally against configured targets
-3. Preview changes with `griffin hub monitor`
-4. Apply changes to hub with `griffin hub apply`
-5. Monitor execution with `griffin hub runs`
+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
 
 ```bash
-npm install -g griffin-cli
+npm install -g @griffin-app/griffin-cli
 ```
 
-## Quick Start
-
-### 1. Initialize
-
-```bash
-griffin init
-```
-
-This creates `.griffin/state.json` which tracks:
-
-- Project ID (auto-detected from package.json or directory name)
-- Environment configurations with their targets
-- Synced monitor state
-- Hub connection settings (optional)
-
-Override project ID with `--project <name>`.
-
-### 2. View Environments
-
-View configured environments:
-
-```bash
-griffin env list
-```
-
-### 3. Create Test Monitors
-
-Create test files in `__griffin__/` directories. These files export test monitors that can be run locally or synced to the hub.
-
-### 4. Run Tests Locally
-
-```bash
-griffin local run local
-```
-
-Executes tests locally using variables from `variables.yaml` for the specified environment.
-
-### 5. Connect to Hub (Optional)
-
-```bash
-griffin hub connect --url https://hub.example.com --token <token>
-```
-
-### 6. Preview Hub Changes
-
-```bash
-griffin hub monitor
-griffin hub monitor production
-```
-
-Shows what will be created, updated, or deleted on the hub for the specified environment.
-
-### 7. Apply to Hub
-
-```bash
-griffin hub apply
-griffin hub apply production
-```
-
-Syncs monitors to the hub for the specified environment.
-
-### 8. Trigger Hub Run
+Or run via npx:
 
 ```bash
-griffin hub run production --monitor <name>
+npx @griffin-app/griffin-cli <command>
 ```
 
-Triggers a monitor execution on the hub in the specified environment.
-
-## Commands
-
-Commands are organized into four groups:
-
-- **Top-level**: Project initialization and utilities
-- **env**: Environment management
-- **local**: Local test execution
-- **hub**: Hub operations (monitor sync, remote execution)
-
-### Top-Level Commands
-
-#### `griffin init`
+The CLI is also available as the `gr` binary.
 
-Initialize Griffin in the current directory.
-
-**Options:**
-
-- `--project <name>` - Project ID (defaults to package.json name or directory name)
+## Quick Start
 
-**Example:**
+### 1. Initialize
 
 ```bash
 griffin init
-griffin init --project my-service
+griffin init --project my-service   # override project ID
 ```
 
-#### `griffin validate`
+Creates `.griffin/state.json` with project ID, default environment, and hub config. Add `.griffin/` to `.gitignore` if you keep local-only state there.
 
-Validate test monitor files without syncing.
-
-**Example:**
-
-```bash
-griffin validate
-```
-
-#### `griffin generate-key`
-
-Generate a cryptographically secure API key for authentication.
-
-**Example:**
+### 2. Optional: environments and variables
 
 ```bash
-griffin generate-key
+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
 ```
 
-### Environment Commands
+Variables are stored in `.griffin/state.json` per environment and used when running monitors (e.g. for `variable("API_BASE")` in the monitor DSL).
 
-#### `griffin env list`
+### 3. Create monitors
 
-List all available environments.
+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`).
 
-**Example:**
+### 4. Validate and run locally
 
 ```bash
-griffin env list
-```
-
-Shows all configured environments with an asterisk (\*) marking the default environment.
-
-### Local Commands
-
-#### `griffin local run [env]`
-
-Run tests locally against an environment. Environment can be specified as a positional argument, or uses the default environment if omitted.
-
-**Example:**
-
-```bash
-griffin local run
-griffin local run staging
-```
-
-Variables are loaded from `variables.yaml` for the specified environment.
-
-### Hub Commands
-
-#### `griffin hub connect`
-
-Configure hub connection settings. When a token is provided, it is stored in the user-level credentials file (`~/.griffin/credentials.json`) for secure, cross-project authentication.
-
-**Options:**
-
-- `--url <url>` - Hub URL (required)
-- `--token <token>` - API authentication token (optional)
-
-**Example:**
-
-```bash
-griffin hub connect --url https://hub.example.com --token abc123
-```
-
-#### `griffin hub login`
-
-Authenticate with the hub using device authorization flow. The received token is stored in the user-level credentials file (`~/.griffin/credentials.json`) for secure access across all projects.
-
-**Example:**
-
-```bash
-griffin hub login
+griffin validate
+griffin test
+griffin test --env staging
 ```
 
-After running this command, you'll be provided with a URL to complete authentication in your browser. Once authenticated, the token will be automatically saved.
-
-#### `griffin hub logout`
-
-Remove stored credentials for the currently configured hub or all hubs.
+`griffin test` runs discovered monitors locally using variables from state for the given environment.
 
-**Options:**
+### 5. Connect to the hub (optional)
 
-- `--all` - Remove credentials for all hubs
+- **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>`.
 
-**Example:**
+### 6. Preview and apply to hub
 
 ```bash
-griffin hub logout
-griffin hub logout --all
+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
 ```
 
-#### `griffin hub status`
-
-Show hub connection status, including whether credentials are configured.
-
-**Example:**
+### 7. Runs and metrics
 
 ```bash
-griffin hub status
+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
 ```
 
-#### `griffin hub runs`
-
-Show recent runs from the hub.
-
-**Options:**
-
-- `--monitor <name>` - Filter by monitor name
-- `--limit <number>` - Number of runs to show (default: 10)
-
-**Example:**
-
-```bash
-griffin hub runs
-griffin hub runs --monitor health-check --limit 5
-```
-
-#### `griffin hub monitor [env]`
-
-Show what changes would be applied to the hub. Environment can be specified as a positional argument, or uses the default environment if omitted.
+## Commands
 
-**Options:**
+Commands are **top-level** or under a **group**. The default environment is `default` unless overridden with `--env <name>` where supported.
 
-- `--json` - Output in JSON format
+| 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 |
 
-**Example:**
+### Top-level commands
 
-```bash
-griffin hub monitor
-griffin hub monitor production
-griffin hub monitor staging --json
-```
+- **`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`.
 
-**Exit codes:**
+### Auth (`griffin auth`)
 
-- `0` - No changes
-- `1` - Error
-- `2` - Changes pending
+- **`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.
 
-#### `griffin hub apply [env]`
+### Environments (`griffin env`)
 
-Apply changes to the hub. Environment can be specified as a positional argument, or uses the default environment if omitted.
+- **`env list`** – List configured environments.
+- **`env add <name>`** – Add an environment.
+- **`env remove <name>`** – Remove an environment.
 
-**Options:**
+### Variables (`griffin variables`)
 
-- `--auto-approve` - Skip confirmation prompt
-- `--dry-run` - Show what would be done without making changes
-- `--prune` - Delete monitors on hub that don't exist locally
+Variables live in `.griffin/state.json` per environment (not in a separate file). Use them in monitors via `variable("KEY")`.
 
-**Example:**
+- **`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>`.
 
-```bash
-griffin hub apply
-griffin hub apply production --auto-approve
-griffin hub apply staging --dry-run
-griffin hub apply production --prune
-```
+### Secrets (`griffin secrets`)
 
-#### `griffin hub run <env>`
+Secrets are stored on the hub per environment. Use them in monitors via `secret("REF")`.
 
-Trigger a monitor run on the hub in the specified environment.
+- **`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`.
 
-**Options:**
+### Integrations (`griffin integrations`)
 
-- `--monitor <name>` - Monitor name to run (required)
-- `--wait` - Wait for run to complete
-- `--force` - Run even if local monitor differs from hub
+- **`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`.
 
-**Example:**
+### Notifications (`griffin notifications`)
 
-```bash
-griffin hub run production --monitor health-check
-griffin hub run staging --monitor health-check --wait
-griffin hub run production --monitor api-check --force
-```
+- **`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 Variables
-
-- `GRIFFIN_ENV` - Default environment to use for commands
-
-### State File
-
-Griffin stores project configuration in `.griffin/state.json`:
-
-```json
-{
-  "stateVersion": 1,
-  "projectId": "my-project",
-  "environments": {
-    "local": {}
-  },
-  "defaultEnvironment": "local",
-  "hub": {
-    "baseUrl": "https://hub.example.com",
-    "clientId": "..."
-  },
-  "discovery": {
-    "pattern": "**/__griffin__/*.{ts,js}",
-    "ignore": ["node_modules/**", "dist/**"]
-  }
-}
-```
-
-**Important:** Add `.griffin/` to `.gitignore` as it contains local project state.
-
-### Credentials File
-
-Griffin stores user-level authentication credentials in `~/.griffin/credentials.json`:
-
-```json
-{
-  "version": 1,
-  "hubs": {
-    "https://hub.example.com": {
-      "token": "...",
-      "updatedAt": "2024-01-24T12:00:00.000Z"
-    }
-  }
-}
-```
-
-This file is automatically created and managed by the CLI when you use `griffin hub login` or `griffin hub connect --token <token>`. Credentials are stored per-hub URL and are available across all projects on your system.
-
-**Security:** The credentials file is created with restricted permissions (0600) to ensure only the owner can read/write.
+### Environment variable
 
-## Environments and Variables
+- **`GRIFFIN_ENV`** – Default environment for commands (if the CLI respects it; otherwise pass `--env` explicitly).
 
-Griffin uses environments to organize test configurations. Each environment maps to a section in `variables.yaml` which contains environment-specific variable values.
+### State file (`.griffin/state.json`)
 
-**Example `variables.yaml`:**
+Stores project configuration:
 
-```yaml
-environments:
-  local:
-    api_host: "localhost:3000"
-    api_key: "local-test-key"
-  staging:
-    api_host: "staging.example.com"
-    api_key: "staging-key"
-  production:
-    api_host: "api.example.com"
-    api_key: "prod-key"
-```
-
-**Example workflow:**
-
-```bash
-# List available environments
-griffin env list
-
-# Run tests against different environments
-griffin local run local
-griffin local run staging
-
-# Sync to hub for specific environment
-griffin hub apply production
-```
-
-## Test Monitor Discovery
+- **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/**"]`).
 
-By default, Griffin discovers test monitors from files in `__griffin__/` directories matching `**/__griffin__/*.{ts,js}`.
+Add `.griffin/` to `.gitignore` if the file contains local-only overrides.
 
-Test files should be TypeScript or JavaScript files that export test monitor objects.
+### Credentials (`~/.griffin/credentials.json`)
 
-## Diff Rules
+User-level auth. Used by `auth login` and `auth connect --token`. Do not commit. Created with restricted permissions (0600).
 
-Griffin computes changes using:
+## Checklist
 
-- **CREATE**: Monitor exists locally but not in state
-- **UPDATE**: Monitor exists in both, but hash differs
-- **DELETE**: Monitor exists in state but not locally
-- **NOOP**: Monitor exists in both with same hash
+**First-time setup**
 
-Change detection uses a SHA-256 hash of the normalized monitor payload.
+- 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.
 
-## Hub API Compatibility
+**Before deploying**
 
-Griffin CLI is compatible with Griffin Hub API v1.
+- `griffin validate` then `griffin test --env <env>`.
+- `griffin plan --env <env>` then `griffin apply --env <env>` (use `--dry-run` or `--auto-approve` as needed).
 
-Required endpoints:
+**Secrets in monitors**
 
-- `POST /monitor` - Create/update monitor
-- `GET /monitor` - List monitors
-- `GET /runs` - List runs
-- `GET /runs/:id` - Get run details
-- `POST /runs/trigger/:monitorId` - Trigger run
+- Create/update with `griffin secrets set REF --env <env>`; ensure ref names match the monitor DSL (e.g. `API_TOKEN`).
 
 ## Development
 
 ```bash
-# Install dependencies
 npm install
-
-# Build
 npm run build
-
-# Run in development
-npm run dev -- <command>
-
-# Example
-npm run dev -- validate
-```
-
-## Architecture
-
-```
-griffin-cli/
-├── src/
-│   ├── commands/           # Command implementations
-│   │   ├── local/          # Local execution commands
-│   │   │   └── run.ts
-│   │   ├── hub/            # Hub operation commands
-│   │   │   ├── connect.ts
-│   │   │   ├── status.ts
-│   │   │   ├── runs.ts
-│   │   │   ├── monitor.ts
-│   │   │   ├── apply.ts
-│   │   │   └── run.ts
-│   │   ├── env.ts          # Environment commands
-│   │   ├── init.ts
-│   │   ├── validate.ts
-│   │   └── generate-key.ts
-│   ├── core/              # Core logic
-│   │   ├── sdk.ts         # Hub SDK client
-│   │   ├── apply.ts       # Apply engine
-│   │   ├── diff.ts        # Diff computation
-│   │   ├── discovery.ts   # Monitor discovery
-│   │   ├── state.ts       # State management
-│   │   ├── variables.ts   # Variable resolution
-│   │   └── project.ts     # Project detection
-│   ├── schemas/           # Type definitions
-│   │   └── state.ts       # State file schemas
-│   ├── cli.ts             # CLI entry point
-│   └── index.ts           # Public API exports
-└── package.json
+npm run dev -- <command>   # e.g. npm run dev -- validate
+npm run test
 ```
 
 ## License