Dino

https://usedino.dev/docs
Admin
Dino is a deterministic verification layer for APIs that tests live GraphQL and REST endpoints,...
Tokens:3,814
Snippets:63
Trust Score:7.5
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install and Run Dino CLI

Source: https://usedino.dev/docs/cli-reference

Install the CLI globally via npm or execute it ad-hoc using npx.

```bash
npm install -g @dino-hq/cli    # then: dino <command>
npx @dino-hq/cli <command>     # no install
```

--------------------------------

### Authentication Configuration

Source: https://usedino.dev/docs/configuration

Example of setting the authentication type to none.

```yaml
auth:
  type: none
```

--------------------------------

### API Docs JSON Output

Source: https://usedino.dev/docs/contracts

Example of the dino-api-docs schema produced by the dino docs command.

```json
{ "formatName": "dino-api-docs", "formatVersion": 1, "title": "…", "operationCount": 19, "health": { … }, "operations": [ … ], "coverage": "full" }
```

--------------------------------

### Scan Result JSON Output

Source: https://usedino.dev/docs/contracts

Example of the ScanResultV1 schema produced by the dino scan command.

```json
{
  "contractVersion": "1.0",
  "core": {
    "title": "API Quality Report",
    "operationCount": 19,
    "health": { "score": 62, "level": "HIGH", "verdict": "At risk" },
    "severityCounts": { "CRITICAL": 0, "HIGH": 14, "MEDIUM": 5, "LOW": 0, "CLEAN": 0, "UNTESTED": 0 },
    "coverage": "full",
    "operations": [ /* per-operation findings, health, coverage */ ]
  },
  "meta": { "generatedAt": "2026-08-13T10:00:00.000Z", "introspectionLevel": "full" }
}
```

--------------------------------

### Example ScanResultV1 JSON output

Source: https://usedino.dev/docs

The structure of the machine-readable scan result returned when using the JSON format.

```json
{
  "contractVersion": "1.0",
  "core": {
    "operationCount": 19,
    "health": { "score": 62, "level": "HIGH", "verdict": "At risk" },
    "coverage": "full",
    "operations": [ /* per-operation findings, health, coverage */ ]
  },
  "meta": { "generatedAt": "…", "introspectionLevel": "full" }
}
```

--------------------------------

### Dino Error JSON Envelope

Source: https://usedino.dev/docs/contracts

Example of the single-line JSON error envelope emitted by Dino on stderr when a command fails.

```json
{"error":{"kind":"transient","message":"Target rate-limited","retryable":"transient","exitCode":4,"suggestion":"Retry after a short backoff"}}
```

--------------------------------

### Initialize Project Configuration

Source: https://usedino.dev/docs/cli-reference

Generate or overwrite the .dino.yml configuration file.

```bash
dino init            # writes .dino.yml in the current directory
dino init --force    # overwrite an existing file
```

--------------------------------

### Initialize Dino configuration

Source: https://usedino.dev/docs

Create a .dino.yml file in the current directory to store endpoint and protocol settings.

```bash
npx @dino-hq/cli init
```

--------------------------------

### Scan using configuration file

Source: https://usedino.dev/docs

Execute a scan using the settings defined in the local .dino.yml file.

```bash
dino scan
```

--------------------------------

### Generate API Documentation

Source: https://usedino.dev/docs/cli-reference

Create documentation from live introspection in markdown or JSON formats.

```bash
dino docs --tenant my-api --format markdown
dino docs --tenant my-api --format json      # dino-api-docs document
```

--------------------------------

### Generate Changelogs

Source: https://usedino.dev/docs/cli-reference

Create a changelog by comparing schema snapshots.

```bash
dino changelog --tenant my-api --from <snapshotId> --fail-on-breaking
```

--------------------------------

### Configure CLI Preferences

Source: https://usedino.dev/docs/cli-reference

Manage CLI settings such as telemetry levels.

```bash
dino config telemetry            # show the current level
dino config telemetry off        # off | crash | all
```

--------------------------------

### Validate Configuration

Source: https://usedino.dev/docs/cli-reference

Check the validity of the .dino.yml configuration file.

```bash
dino validate
```

--------------------------------

### Run a one-off API scan

Source: https://usedino.dev/docs

Execute a scan against a GraphQL or REST endpoint without requiring a configuration file.

```bash
npx @dino-hq/cli scan --endpoint https://your-api.com/graphql
```

--------------------------------

### Basic .dino.yml Configuration

Source: https://usedino.dev/docs/configuration

The minimal configuration required to define an API endpoint and protocol.

```yaml
# yaml-language-server: $schema=https://usedino.dev/schema.json
# Generated by dino init: see https://docs.usedino.dev for all options

endpoint: https://your-api.com/graphql
protocol: graphql
```

--------------------------------

### Configure Dino MCP server

Source: https://usedino.dev/docs/for-agents

Add the Dino MCP server to your client configuration using the required API key.

```json
{
  "mcpServers": {
    "dino": {
      "command": "npx",
      "args": ["-y", "@dino-hq/mcp-server"],
      "env": { "DINO_API_KEY": "dino_k_live_..." }
    }
  }
}
```

--------------------------------

### Run API Verification Scans

Source: https://usedino.dev/docs/cli-reference

Execute verification passes against APIs using endpoints, protocols, or local configuration files.

```bash
dino scan --endpoint https://your-api.com/graphql
dino scan --endpoint https://your-api.com --protocol rest --spec-url https://your-api.com/openapi.json
dino scan                      # uses .dino.yml
```

--------------------------------

### Run Dino scan via CLI

Source: https://usedino.dev/docs/for-agents

Execute a scan against an API endpoint with specific failure thresholds and output formatting.

```bash
dino scan --endpoint https://your-api.com/graphql --fail-on-high --format json --quiet
```

--------------------------------

### Compare Schema Snapshots

Source: https://usedino.dev/docs/cli-reference

Detect breaking changes by comparing the current schema against a saved snapshot.

```bash
dino diff --tenant my-api --fail-on-breaking
```

--------------------------------

### Schedule Scans with Watch

Source: https://usedino.dev/docs/cli-reference

Run recurring scans in observe or enforce mode.

```bash
dino watch --tenant my-api --autonomy enforce --interval 600
```

--------------------------------

### CLI: dino scan

Source: https://usedino.dev/docs/for-agents

The CLI interface allows agents to scan an API endpoint and receive a deterministic verdict via exit codes and JSON output.

```APIDOC
## CLI Command: dino scan

### Description
Executes a scan against a specified API endpoint to verify its health and compliance. The agent can branch logic based on the process exit code and parse the JSON output for detailed findings.

### Usage
`dino scan --endpoint <url> [options]`

### Options
- **--endpoint** (string) - Required - The URL of the API to scan.
- **--fail-on-high** (flag) - Optional - Exits with code 3 if HIGH or CRITICAL findings are detected.
- **--format** (string) - Optional - Output format (e.g., 'json').
- **--quiet** (flag) - Optional - Suppresses non-essential output.

### Exit Codes
- **0**: Clean
- **2**: Usage error
- **3**: Policy gate failed
- **4**: Transient error
- **5**: Configuration error
- **6**: Partial results
- **70**: Crash
```

--------------------------------

### MCP Server Tools

Source: https://usedino.dev/docs/for-agents

The MCP server provides a set of tools for agents to perform scans, retrieve results, and evaluate quality gates.

```APIDOC
## MCP Tools

### Description
Tools available via the `@dino-hq/mcp-server` for integration into MCP-compliant clients.

### Available Tools
- **run_scan**: Initiates a non-blocking scan.
- **get_scan_result**: Polls for the results of a previously initiated scan.
- **get_findings**: Retrieves specific findings from a scan.
- **get_agent_readiness**: Returns the readiness status (ready, partial, not_ready, degraded) with a breakdown.
- **compare_scans**: Diffs two scan results.
- **evaluate_quality_gate**: Checks a configured quality gate.
```

--------------------------------

### Perform an automated scan for agents

Source: https://usedino.dev/docs

Run a scan with JSON output and quiet mode to facilitate machine parsing of the verdict.

```bash
dino scan --endpoint https://your-api.com/graphql --format json --quiet
```

--------------------------------

### REST API Configuration

Source: https://usedino.dev/docs/configuration

Configuration for REST APIs requiring a specUrl to an OpenAPI document.

```yaml
endpoint: https://your-api.com
protocol: rest
specUrl: https://your-api.com/openapi.json
```

--------------------------------

### Agent verification loop

Source: https://usedino.dev/docs

The conceptual loop for an agent to iteratively improve an API based on scan results.

```text
agent changes the API → dino scan → read verdict + exit code → fix → dino scan again
```

--------------------------------

### Lint Schema Descriptions

Source: https://usedino.dev/docs/cli-reference

Check for undocumented operations in the schema.

```bash
dino lint --tenant my-api --fail-on-undocumented
```

--------------------------------

### Branch on Dino exit codes

Source: https://usedino.dev/docs/contracts

Use the exit code from a Dino command to determine the appropriate action in a CI/CD pipeline or script.

```bash
dino scan --endpoint "$URL" --fail-on-high --format json --quiet
case $? in
  0)  echo "clean, continue" ;;
  3)  echo "policy gate failed, do not ship" ;;
  6)  echo "partial coverage, decide (or use --accept-partial)" ;;
  4)  echo "transient, back off and retry" ;;
  2|5) echo "usage/config, fix input, do not retry as-is" ;;
  70) echo "crash, surface to a human" ;;
esac
```

--------------------------------

### Branch on scan exit codes

Source: https://usedino.dev/docs

Use exit codes to gate deployments or handle errors in automated pipelines.

```bash
dino scan --endpoint https://your-api.com/graphql --fail-on-high --format json --quiet
case $? in
  0) echo "clean: safe to continue" ;;
  3) echo "policy gate failed: HIGH/CRITICAL findings, do not ship" ;;
  6) echo "partial coverage: reduced evidence, decide explicitly" ;;
  *) echo "usage/transient/config/crash: recover or stop" ;;
esac
```
Tokens:
Raw