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

> Configure Dino with a simple YAML file in your project root.

# .dino.yml

Dino is configured through a `.dino.yml` file in your project root. Run `dino init` to generate one interactively, or create it manually.

For **REST (OpenAPI)** APIs, discovery and routing live in a **tenant** file under `tenants/<id>.yml`. Point the CLI at that tenant with `tenant:` in `.dino.yml` or `dino scan --tenant <id>`.

## Minimal config (GraphQL, ad-hoc)

```yaml theme={null}
# yaml-language-server: $schema=https://usedino.dev/schema.json
endpoint: https://api.example.com/graphql
protocol: graphql
format: json
```

That is enough for a GraphQL-only ad-hoc run: the pipeline uses sensible defaults and runs all shipped quality modules that apply (the REST fuzzer participates when REST operations exist).

## Minimal pointer (REST, tenant mode)

```yaml theme={null}
# yaml-language-server: $schema=https://usedino.dev/schema.json
tenant: my-api
format: json
```

Create `tenants/my-api.yml` (see below), then:

```bash theme={null}
dino scan --tenant my-api
```

## Full reference (`.dino.yml`)

| Field             | Type                       | Default             | Description                                                                                                                        |
| ----------------- | -------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `endpoint`        | URL                        | —                   | GraphQL endpoint URL for **ad-hoc** scans (`tenant` unset).                                                                        |
| `protocol`        | `"graphql"`                | `"graphql"`         | **Ad-hoc CLI config:** GraphQL only. REST is **not** selected here — use tenant `apis[].type: rest` and OpenAPI discovery instead. |
| `format`          | `"json"` \| `"markdown"`   | `"json"`            | Output format for scan results.                                                                                                    |
| `tenant`          | string                     | —                   | Tenant ID. Loads config from `tenants/<id>.yml`. Required for multi-environment, auth, and **REST/OpenAPI** setups.                |
| `environment`     | string                     | —                   | Target environment (e.g., `staging`, `production`).                                                                                |
| `snapshotDir`     | string                     | `".dino/snapshots"` | Directory for schema snapshots used by `diff`, `lint`, `changelog`.                                                                |
| `aiKey`           | string                     | —                   | Anthropic API key for AI reasoning. Prefer the `DINO_AI_KEY` env var instead.                                                      |
| `auth.enabled`    | boolean                    | `false`             | Enable authenticated scans. Required for RBAC matrix when your tenant uses auth.                                                   |
| `auth.role`       | string                     | —                   | Default auth role for scans (e.g., `USER`, `ADMIN`).                                                                               |
| `autonomy.level`  | `"observe"` \| `"enforce"` | `"observe"`         | Shadow Mode level for `dino watch`.                                                                                                |
| `rateLimit.burst` | integer (1–500)            | Tier default        | Burst size for rate limit testing.                                                                                                 |

## REST APIs — `tenants/<id>.yml`

Define each API under `apis[]`. The discovery plugin routes on `type` (`graphql` vs `rest`) and `source` (`introspection` vs `openapi`).

```yaml theme={null}
schemaVersion: 1
id: my-api
name: My REST API
apis:
  - name: main
    type: rest
    source: openapi
    specPath: https://api.example.com/openapi.json
environments:
  default:
    endpoints:
      main: https://api.example.com
    timeout: 30000
defaultEnvironment: default
auth:
  adapter: none
  adapterConfig: {}
  roles: []
agents: []
```

### `apis[]` fields

| Field      | Type                             | Description                                                                   |
| ---------- | -------------------------------- | ----------------------------------------------------------------------------- |
| `name`     | string                           | API identifier (must match a key under `environments.<env>.endpoints`)        |
| `type`     | `"graphql"` or `"rest"`          | Protocol                                                                      |
| `source`   | `"introspection"` or `"openapi"` | Discovery method                                                              |
| `specPath` | string                           | URL or repo-relative path to the OpenAPI document (**REST / `openapi` only**) |

## JSON Schema

The `# yaml-language-server` comment at the top of your config file enables IDE autocomplete if you use the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) in VS Code.

```yaml theme={null}
# yaml-language-server: $schema=https://usedino.dev/schema.json
```

`dino init` adds this comment automatically.

## Config file search order

Dino uses [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) to find your config. It searches in this order:

1. `.dino.yml` or `.dino.yaml`
2. `.dinorc` (JSON or YAML)
3. `.dinorc.json`, `.dinorc.yaml`, `.dinorc.yml`
4. `package.json` → `"dino"` key

<Warning>
  Executable config files (`.js`, `.ts`, `.cjs`, `.mjs`) are **blocked** for security. Only YAML and JSON configs are loaded.
</Warning>

## Precedence

When the same setting is defined in multiple places:

```
CLI flags  >  Environment variables  >  .dino.yml  >  Smart defaults
```

For example, `--format markdown` overrides `format: json` in your config file.

## Smart defaults

If you omit fields, Dino applies sensible defaults:

* **All shipped pipeline modules enabled** (RBAC matrix auto-skips when auth is not configured; `rest-fuzzer` runs when REST operations are discovered)
* **Pipeline timeout:** 300 seconds
* **Per-request timeout:** 30 seconds
* **Snapshot dir:** `.dino/snapshots`
* **Watch interval:** 60 seconds
* **Watch autonomy:** `observe` (safe default — never blocks CI unless you opt in)

## Examples

### Ad-hoc scan (GraphQL, no tenant)

```yaml theme={null}
endpoint: https://api.myapp.com/graphql
protocol: graphql
format: json
```

### Authenticated scan with RBAC testing

```yaml theme={null}
endpoint: https://api.myapp.com/graphql
protocol: graphql
format: json
auth:
  enabled: true
  role: USER
```

### REST scan (tenant)

`tenants/acme-rest.yml` defines `apis[].type: rest` and `specPath`. Then:

```yaml theme={null}
tenant: acme-rest
format: json
```

```bash theme={null}
dino scan --tenant acme-rest --env production
```

### CI/CD with enforce mode

```yaml theme={null}
endpoint: https://staging.myapp.com/graphql
protocol: graphql
format: json
autonomy:
  level: enforce
```

<Info>
  See the [Installation guide](/installation) for setting `DINO_AI_KEY` and `DINO_API_TOKEN` without putting secrets in your config file.
</Info>