Run Dino scans on a repeating schedule. Shadow Mode monitors your API continuously, tracks health scores over time, detects schema drift, and optionally enforces breaking-change gates.
Designed for long-running environments (staging servers, CI monitors, containers) and single-shot CI checks (--once).
Usage
dino watch --tenant <id> [flags]
Flags
| Flag | Type | Default | Description |
|---|
--tenant | string | — | Required. Tenant ID (or set in .dino.yml) |
--env | string | Tenant default | Target environment |
--format | "markdown" | "json" | "markdown" | Output format |
--quiet | boolean | false | Suppress stdout output |
--autonomy | "observe" | "enforce" | "observe" | Shadow Mode autonomy level |
--interval | number | 300 | Seconds between iterations |
--iterations | number | Infinity | Number of iterations before exiting |
--once | boolean | false | Run exactly one iteration and exit (shorthand for --iterations 1) |
--tools | string[] | All tools | Comma-separated list of tools to run |
--modules | string[] | All modules | Comma-separated list of modules to scope |
--reasoning | boolean | false | Enable AI-powered reasoning (requires DINO_AI_KEY) |
--timeout | number | 300000 | Pipeline timeout per iteration in milliseconds |
--snapshot-dir | string | .dino/snapshots | Directory for schema snapshots |
--history-limit | number | 100 | Maximum history entries to retain on disk |
--max-consecutive-failures | number | 5 | Exit non-zero after this many consecutive failures |
Authentication Flags
| Flag | Type | Default | Description |
|---|
--auth | object | { enabled: false } | Enable authenticated scanning |
--ai-key | string | DINO_AI_KEY env var | API key for AI reasoning |
Autonomy Levels
| Level | Behavior |
|---|
observe | Run scans and log results. Never fails on breaking changes. Default. |
enforce | Exit with code 1 immediately when breaking schema changes are detected. |
In enforce mode, a single breaking change terminates the watch loop. Use this in CI or pre-deploy gates where you want hard stops on API regressions.
Examples
Observe mode (default)
dino watch --tenant acme --env staging
[watch] iteration 1: 24 ops, health 95, 0 breaking
[watch] iteration 2: 24 ops, health 95, 0 breaking
[watch] iteration 3: 26 ops, health 88, 1 breaking
Ctrl+C or SIGTERM.
Enforce mode in CI
dino watch --tenant acme --env production --autonomy enforce --once
- name: API health gate
run: dino watch --tenant acme --env production --autonomy enforce --once
Custom interval and iteration count
dino watch --tenant acme --interval 60 --iterations 10
Long-running container monitor
dino watch --tenant acme --env production --interval 900 --history-limit 500
SIGTERM gracefully for container orchestrators.
Use --once for CI pipelines and --iterations for time-boxed monitoring sessions. Omit both for indefinite monitoring.
History
Each iteration writes a history entry to .dino/history/. Entries include:
| Field | Description |
|---|
runId | Unique identifier for the iteration |
timestamp | ISO 8601 timestamp |
healthScore | Global health score (0-100, 100 = healthy) |
operationCount | Number of discovered operations |
toolsRun / toolsCompleted / toolsFailed | Tool execution counts |
degraded | Whether the pipeline ran in degraded mode |
schemaChanges | Added, removed, modified, and breaking change counts |
--history-limit to control disk usage for long-running instances.
Circuit Breaker
If iterations fail consecutively, the watch loop exits to prevent runaway resource consumption.
[watch] 5 consecutive failures -- exiting. Last error: Discovery timeout
--max-consecutive-failures (default: 5). A single successful iteration resets the counter.
Graceful Shutdown
The watch loop handles SIGINT (Ctrl+C) and SIGTERM signals. When interrupted:
- The current sleep interval is cancelled immediately
- No new iterations start
- The command exits with code 0
Exit Codes
| Code | Meaning |
|---|
0 | All iterations completed, or gracefully interrupted |
1 | enforce mode triggered by breaking changes, circuit breaker tripped, or invalid flags |
