@supercheck/cli 0.1.0-beta.2 → 0.1.0-beta.4

package/README.md

@@ -1,6 +1,18 @@
 # @supercheck/cli
 
-Supercheck CLI — monitoring-as-code for Playwright and k6.
+Open-Source Testing, Monitoring, and Reliability — as Code.
+
+[![npm version](https://img.shields.io/npm/v/@supercheck/cli.svg)](https://www.npmjs.com/package/@supercheck/cli)
+[![License](https://img.shields.io/badge/license-Supercheck_Community_License-blue.svg)](LICENSE)
+
+The Supercheck CLI provides a first-class command-line interface for managing your testing and monitoring infrastructure as code. It is designed for CI/CD integration, automation, and power-user workflows.
+
+## Features
+
+- **Monitoring-as-Code**: Define monitors, tests, jobs, and status pages in TypeScript.
+- **CI/CD Integration**: Trigger jobs and wait for results directly from your pipeline.
+- **Full Resource Management**: Manage all resources (tests, monitors, jobs, variables, tags, notifications) from the terminal.
+- **Modern UX**: Spinners, colorized output, status indicators, and interactive prompts.
 
 ## Installation
 
@@ -8,31 +20,99 @@ Supercheck CLI — monitoring-as-code for Playwright and k6.
 npm install -g @supercheck/cli
 ```
 
-Or use with npx:
+Or run directly with `npx`:
 
 ```bash
-npx @supercheck/cli
+npx @supercheck/cli --help
 ```
 
 ## Quick Start
 
-```bash
-# Initialize a new project
-supercheck init
-
-# Authenticate
-supercheck login --token <your-token>
-
-# Validate config
-supercheck config validate
-
-# Check API health
-supercheck health
-```
+1. **Initialize a new project**:
+   ```bash
+   supercheck init
+   ```
+   This creates a `supercheck.config.ts` and a `_supercheck_` directory with example tests.
+
+2. **Authenticate**:
+   ```bash
+   supercheck login --token sck_live_...
+   ```
+   You can generate a CLI token in your Dashboard under **Project Settings > CLI Tokens**.
+
+3. **Pull existing resources**:
+   ```bash
+   supercheck pull
+   ```
+
+4. **Preview & Deploy**:
+   ```bash
+   supercheck diff
+   supercheck deploy
+   ```
+
+## Command Reference
+
+### Authentication
+
+| Command | Description |
+|---|---|
+| `supercheck login --token <token>` | Authenticate with a CLI token |
+| `supercheck logout` | Clear stored credentials |
+| `supercheck whoami` | Show current authentication context |
+
+### Monitoring-as-Code
+
+| Command | Description |
+|---|---|
+| `supercheck init` | Initialize a new project with config and example tests |
+| `supercheck pull` | Sync cloud resources to local config |
+| `supercheck diff` | Preview changes between local config and cloud |
+| `supercheck deploy` | Apply local config changes to the cloud |
+| `supercheck destroy --force` | Remove all managed resources from the cloud |
+| `supercheck config validate` | Validate your `supercheck.config.ts` |
+
+### Jobs & Runs
+
+| Command | Description |
+|---|---|
+| `supercheck job list` | List all jobs |
+| `supercheck job create` | Create a new job |
+| `supercheck job run` | Run a job immediately |
+| `supercheck job trigger <id> --wait` | Trigger a job and wait for completion (CI/CD) |
+| `supercheck run list` | List recent execution runs |
+| `supercheck run stream <id>` | Stream live console output |
+
+### Tests & Monitors
+
+| Command | Description |
+|---|---|
+| `supercheck test list` | List all tests |
+| `supercheck test create` | Create a new test |
+| `supercheck test validate` | Validate local test scripts |
+| `supercheck monitor list` | List all monitors |
+| `supercheck monitor status <id>` | Check real-time monitor status |
+
+### Variables, Tags & Notifications
+
+| Command | Description |
+|---|---|
+| `supercheck var list / get / set / delete` | Manage project variables |
+| `supercheck tag list / create / delete` | Manage tags |
+| `supercheck notification list / delete` | Manage notification providers |
+| `supercheck alert history` | View alert history |
+| `supercheck audit` | View audit logs (admin) |
+
+### Utilities
+
+| Command | Description |
+|---|---|
+| `supercheck health` | Check API health |
+| `supercheck locations` | List available execution locations |
 
 ## Configuration
 
-Create a `supercheck.config.ts` in your project root:
+The `supercheck.config.ts` file is the source of truth for your project configuration.
 
 ```typescript
 import { defineConfig } from '@supercheck/cli'
@@ -40,40 +120,70 @@ import { defineConfig } from '@supercheck/cli'
 export default defineConfig({
   schemaVersion: '1.0',
   project: {
-    organization: 'my-org',
-    project: 'my-project',
+    organization: 'my-org-id',
+    project: 'my-project-id',
   },
   tests: {
     playwright: {
       testMatch: '_supercheck_/tests/**/*.pw.ts',
-      browser: 'chromium',
     },
     k6: {
       testMatch: '_supercheck_/tests/**/*.k6.ts',
     },
   },
+  monitors: [
+    {
+      name: 'API Health',
+      type: 'http_request',
+      target: 'https://api.example.com/health',
+      frequencyMinutes: 5,
+    }
+  ]
 })
 ```
 
-## File Conventions
+## CI/CD Integration
 
-```
-_supercheck_/
-├── tests/
-│   ├── homepage.pw.ts       # Playwright test
-│   └── load-test.k6.ts      # k6 test
-├── monitors/
-│   └── api-monitor.ts       # Monitor definition
-└── status-pages/
-    └── main-status.ts       # Status page definition
+### GitHub Actions
+
+```yaml
+- name: Run E2E Tests
+  run: npx @supercheck/cli job trigger ${{ secrets.SUPERCHECK_JOB_ID }} --wait --json
+  env:
+    SUPERCHECK_TOKEN: ${{ secrets.SUPERCHECK_TOKEN }}
 ```
 
-## Development
+### GitLab CI
 
-```bash
-npm install
-npm run dev        # Watch mode
-npm run build      # Production build
-npm run typecheck  # Type checking
-npm run supercheck # Run CLI in dev mode
+```yaml
+test:
+  image: node:18
+  script:
+    - npm install -g @supercheck/cli
+    - supercheck job trigger $SUPERCHECK_JOB_ID --wait
+  variables:
+    SUPERCHECK_TOKEN: $SUPERCHECK_TOKEN
 ```
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `SUPERCHECK_TOKEN` | CLI token for authentication (CI/CD) |
+| `SUPERCHECK_TRIGGER_KEY` | Trigger key for `job trigger` |
+| `SUPERCHECK_URL` | Custom API URL (self-hosted) |
+
+## Global Options
+
+| Flag | Description |
+|---|---|
+| `--json` | Output in JSON format |
+| `--quiet` | Suppress non-essential output |
+| `--debug` | Enable debug logging |
+| `-v, --version` | Show CLI version |
+
+## Links
+
+- [Website](https://supercheck.io)
+- [Documentation](https://docs.supercheck.io)
+- [GitHub](https://github.com/supercheck-io/supercheck)