dino watch

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

Runs every 5 minutes until interrupted with Ctrl+C or SIGTERM.

Enforce mode in CI

dino watch --tenant acme --env production --autonomy enforce --once

Runs a single iteration. If breaking changes are detected, exits with code 1. Perfect for CI pipelines.

- name: API health gate
  run: dino watch --tenant acme --env production --autonomy enforce --once

api-gate:
  script:
    - dino watch --tenant acme --env production --autonomy enforce --once

Custom interval and iteration count

dino watch --tenant acme --interval 60 --iterations 10

Runs 10 iterations, 60 seconds apart, then exits with code 0.

Long-running container monitor

dino watch --tenant acme --env production --interval 900 --history-limit 500

Runs every 15 minutes, keeps the last 500 history entries. Handles 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

Use --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

The threshold is controlled by --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

dino scan — Single pipeline run
dino diff — One-off schema diff
dino validate — Validate .dino.yml before watching

Get Started

CLI Reference

Configuration

How Dino Works

Security & Compliance

Reference

Usage

Flags

Authentication Flags

Autonomy Levels

Examples

Observe mode (default)

Enforce mode in CI

Custom interval and iteration count

Long-running container monitor

History

Circuit Breaker

Graceful Shutdown

Exit Codes

​Usage

​Flags

​Authentication Flags

​Autonomy Levels

​Examples

​Observe mode (default)

​Enforce mode in CI

​Custom interval and iteration count

​Long-running container monitor

​History

​Circuit Breaker

​Graceful Shutdown

​Exit Codes

​Related

Usage

Flags

Authentication Flags

Autonomy Levels

Examples

Observe mode (default)

Enforce mode in CI

Custom interval and iteration count

Long-running container monitor

History

Circuit Breaker

Graceful Shutdown

Exit Codes

Related