> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedino.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# dino watch

> Continuous API monitoring with Shadow Mode -- observe or enforce on a schedule

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

```bash theme={null}
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. |

<Warning>
  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.
</Warning>

## Examples

### Observe mode (default)

```bash theme={null}
dino watch --tenant acme --env staging
```

```text theme={null}
[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

```bash theme={null}
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.

<CodeGroup>
  ```yaml GitHub Actions theme={null}
  - name: API health gate
    run: dino watch --tenant acme --env production --autonomy enforce --once
  ```

  ```yaml GitLab CI theme={null}
  api-gate:
    script:
      - dino watch --tenant acme --env production --autonomy enforce --once
  ```
</CodeGroup>

### Custom interval and iteration count

```bash theme={null}
dino watch --tenant acme --interval 60 --iterations 10
```

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

### Long-running container monitor

```bash theme={null}
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.

<Tip>
  Use `--once` for CI pipelines and `--iterations` for time-boxed monitoring sessions. Omit both for indefinite monitoring.
</Tip>

## 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.

```text theme={null}
[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:

1. The current sleep interval is cancelled immediately
2. No new iterations start
3. 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 |

## Related

* [`dino scan`](/cli/scan) -- Single pipeline run
* [`dino diff`](/cli/diff) -- One-off schema diff
* [`dino validate`](/cli/validate) -- Validate `.dino.yml` before watching