# Dino > The deterministic verification layer for APIs. An independent, reproducible verdict on whether an API change is correct, secure, and safe to ship. ## Home Dino is the deterministic verification layer for APIs. Point Dino at a running GraphQL or REST API and it tests the live surface, evaluates the evidence, and returns a deterministic verdict you can gate a deploy on — the same evidence and the same policy always produce the same result. There is no test suite to write or keep green. Dino is built for a world where coding agents write most of the changes. It flags the change that breaks your consumers before it reaches production, so you can merge what your agents write knowing the running API still works. Dino does not replace your coding agent — it is the independent verifier the agent, or your CI, calls before shipping an API change. It works with both REST and GraphQL and runs locally through the `@dino-hq/cli` command line, with no account needed for local scans. Agents set up a Dino Organization and its APIs through the hosted MCP server at https://api.usedino.dev/mcp, a remote URL you connect over OAuth, not an npm package (there is no `@dino-hq/mcp-server` to install); the human verifies their email, chooses or creates the Organization, confirms its residency, and approves access in the browser. Either way Dino emits a machine-readable verdict (a versioned JSON result plus documented exit codes) that CI and agents can branch on without a human interpreting prose. ## For coding agents You (the coding agent) drive the `dino` CLI. A human supplies values you do not have (API URL, secrets) when Dino asks. The canonical, version-matched copy of this skill ships inside the CLI (run `dino skill`); the text here is a snapshot so you can start from a cold workspace. `dino schema` prints every command, flag and exit code of the installed version as JSON. The loop: set up, verify, read, fix, reverify. 1. Install: `curl -fsSL https://usedino.dev/install.sh | sh` (standalone binary, no Node.js on macOS and most Linux; where no binary fits (e.g. Alpine/musl) it falls back to npm, which needs Node.js 22+; in scripts and agents run it under `bash -o pipefail -c '…'` and pin a version with `sh -s `), or `brew install dino-hq/tap/dino`, or `npm install -g @dino-hq/cli` (Node 22+), or run pinned with no install: `npx -y @dino-hq/cli@`. See https://usedino.dev/docs/install. No account is needed for local scans. 2. Set up (once per project): `dino init --endpoint --protocol --auth ` writes a flat `.dino.yml`. Add `--yes` for non-interactive / agent use. - `--protocol rest` also needs `--spec-url `. - `--auth header` also needs `--auth-header ` and `--auth-value-env `. - `--auth oauth2` also needs `--oauth2-token-endpoint`, `--oauth2-client-id-env`, `--oauth2-client-secret-env`. 3. Verify: `dino scan --fail-on-high --format json --quiet` runs the checks and returns findings plus a verdict. 4. Read: the exit code is your pass / not-pass signal; the JSON carries the detail and the next step. 5. Fix the API or its config, then reverify. Repeat until it passes at your gate. Secret rule (important): you pass the NAME of an environment variable, never the secret value. Ask the human to set that env var themselves. Never put a token, password, or client secret into a command, a file, or your own message. Missing input (human-agent resume): if `dino init` (or `dino scan` with no resolvable endpoint) is missing a value, it exits non-zero and prints a JSON envelope on stderr whose `nextAction` is `{ "type": "ask_user", "inputs": [...], "resume": { "type": "run_command", "bin": "dino", "args": [...] } }`. Each input carries `field`, `flag`, `envVar`, `secret`, plus `reason` (why Dino needs it) and `example` (format; for `secret: true`, shape and where to set it, never a value). Ask the human for each input, then re-run `resume.bin` with `resume.args`, appending each collected input by its `flag`. Do not guess values. Exit codes: `0` clean or below threshold (pass); `2` usage error (fix the flags, read the envelope suggestion); `3` policy failure (findings exceeded the gate); `4` transient (retry later); `5` config error (fix `.dino.yml`); `6` partial (some checks did not complete, NOT a full pass); `70` crash. The rule that matters most: anything that is not a substantiated pass is not a pass. Dino reports UNTESTED, INCOMPLETE, or partial honestly, so never read a missing, degraded, or partial result as if it passed. MCP (set up a Dino Organization and its APIs): the hosted MCP server is a remote URL you connect over OAuth, not an npm package (there is no `@dino-hq/mcp-server` to install). In Claude Code: `claude mcp add --transport http dino https://api.usedino.dev/mcp`, then `claude mcp login dino` (or `/mcp`, authenticate `dino`); adding alone only saves the configuration and leaves the server at `Needs authentication`. The human signs in to Dino in the browser: verifies their email with a one-time code, chooses one of their Organizations or creates one (a new Organization needs its name and data residency confirmed: United States or European Union, which cannot change later), and approves your access. You never pick the Organization or residency for them. Once connected, run: `bootstrap` (admit the API, its Environment and Target; no secrets, no scan) → `create_auth_profile` (no secret) → `open_credential_handoff` only when the `nextAction` is `credential_required` (give the human the link; they type the credential on Dino's page, never in chat) → `get_auth_profile` → `propose_target_connection` with the human's answers on where scans run and for which purposes → the human's approval on Dino's approval page → `get_target_connection`. For a Target whose API signs in with a login, create the identity with strategy `login_flow` and propose the login steps with `propose_authentication_flow` (secrets only as `{{name}}` placeholders); the human then enters each named secret on the handoff page. The human approves the Target Connection on Dino's approval page, never through you. Authorizing a Target Connection grants Dino authority over the human's system, so only a human signed in to Dino directly can decide it: Dino refuses `submit_human_action_response` for this decision from an agent, even one acting for the human. `get_human_action_request` returns an `approvalUrl`: give the human that link, tell them it shows exactly what the Connection allows (destination, scope, credentials and every limit), and poll `get_presentation_request` until it is decided. Credential entry is not authorization: the one human approval is the Target Connection, bound to the exact configuration the human reviewed, and a changed configuration needs a new approval. Follow the `nextAction` in every result; after a reconnect, read current state with the get tools instead of assuming it. A pending, refused, or expired result is not success: say what the human must do next. New Organizations start on the free plan; `get_commercial_state` shows the plan and entitlements. To switch Organizations, clear the stored authorization first (Claude Code: `claude mcp logout dino`, or **Clear authentication** in `/mcp`), then `claude mcp login dino` and choose the other one; reconnecting alone reuses the current Organization. Protected Discovery (a credentialed OpenAPI document or GraphQL introspection): Dino never keeps the credential. Before anything from the response is stored, Dino checks it for protected credential material: the credential and each of its secret components at any length (a Basic password, a login-flow secret, a token or session the flow acquired), in the literal text, its escaped and decoded forms, and the response headers Dino records. Identifiers such as usernames are only checked as part of the whole credential. On a match the response is withheld: nothing of it is kept, the Operation stops `LIFECYCLE_FAILED` with `CREDENTIAL_REFLECTED` and the detail "The response matched protected credential material and was withheld.", and the earlier usable Discovery stays current. The check is conservative: a short or common credential value (`1234`, `admin`, a word that also names a schema type) withholds any response that happens to contain it, and a withheld response is never a confirmed leak, an invalid credential, or a credential-health statement. Its `nextAction` is `provide_input` (`discovery_response_withheld`): check that the source is the intended endpoint; if the match is a coincidence, upload the document or SDL instead, or ask the human to use a more distinctive credential. There is no minimum credential length. Follow the `nextAction` in every result; after a reconnect, read current state with the get tools instead of assuming it. To admit Initial Discovery for a Target you know only by its id (for example from `list_auth_profiles`), read its `apiId` and `environmentId` from `list_target_connections`; you do not need the original `bootstrap` response. A pending, refused, or expired result is not success: say what the human must do next. New Organizations start on the free plan; `get_commercial_state` shows the plan and entitlements. To switch Organizations, clear the stored authorization first (Claude Code: `claude mcp logout dino`, or **Clear authentication** in `/mcp`), then `claude mcp login dino` and choose the other one; reconnecting alone reuses the current Organization. Human tasks on Dino's task page. Some work belongs to the human: a secret, an approval, stopping access, a Dino service key. You start it or ask for it, hand the human a link to Dino's task page, and read the outcome yourself. The human does it signed in to Dino directly; a consequential decision needs a sign-in from the last 15 minutes, so the page may ask them to sign in again first. - Connect an OAuth2 API on one page: `start_connect_journey` takes the Target, either a name for a new identity or an existing `authProfileId`, and the human's answers on where scans run and for which purposes. Give the human the pending step's `taskUrl`; on that page they configure the OAuth2 client (unless you sent a typed draft), enter the client secret, and approve the exact Connection. Poll `get_presentation_request` with the Request id. The journey ends `connect_proposed` and links the approval Request in `checkpoint.createdArtifactReferences`. An identity that already has its configuration and secret goes straight to the approval. - Ask a human to stop access: you never stop access yourself. `request_operator_action` names one action and your `why`: `credential.revoke` with a `credentialReferenceId`, or `connection.suspend`, `connection.revoke` or `connection.retire` with `targetId`, `connectionId` and `version`. The human sees what the action affects and confirms once on the page. A human can also stop access with no agent and no link, at `https://api.usedino.dev/task?action=stop-access`. - Dino service keys are issued by humans: issuing, regenerating and revoking a Dino service key happens only on `https://api.usedino.dev/task?action=service-keys`. `list_service_keys` gives you ids, each key's Service Account role, whether it is active, and that `taskUrl`, never key material. A key authenticates as its own Service Account, not as the human who issued it. Dino shows a key once; if it was not stored, ask the human to regenerate it. - Read why a Request ended: every Request carries `status` and `statusReasonCode`. For example, FAILED with `operator_action_already_in_effect` means another action had already stopped that access, so the human's confirmation changed nothing. Discover an API and manage its sources. Discovery turns an API's OpenAPI document or GraphQL schema into Dino's canonical inventory. Over MCP the agent finds the exact estate, sends the source, reads what Dino discovered, and manages the source's lifecycle. Every result names its next step. - Find the exact estate from a name: `find_apis` with the API's name returns every API whose name matches exactly, ignoring ASCII letter case only (other letters must match as written), never a similar one; `ambiguous` (with `matchCount`) means several match, so ask your human which. `get_api_estate` lists every Environment with its Target count and a page of 20 Targets (pass `nextCursor` as `cursor`). Each Target carries its destination, the Connection Dino would use for anonymous Discovery contact (or `discoveryConnectionReason`, why there is none it could use), its newest Operation, its current generation, and a `nextAction`: `estate_discovery_in_progress`, `estate_discovery_available`, `estate_discovery_failed` or `estate_discovery_source_required`. Several Environments or Targets may share a name: tell them apart by id. This is how a fresh agent recovers after losing context. - Send a file Dino should read exactly as it is: For an OpenAPI document or GraphQL SDL you should not copy into the conversation, call `open_source_intake` with the `apiId`, its `format` (`json` or `yaml` for REST, `sdl` for GraphQL) and, if you know them, its `expectedDigest`, `expectedByteLength` and `provenance` (where it came from: `server`, `repository`, `registry_export`, `client_bundle` or `unknown`, plus revision, variant and whether it was bundled; recorded as stated, never as proof). Give your human `transfer.taskUrl`: they choose the file on Dino's page, signed in. Or their own tool sends the raw bytes with their own credential as an authenticated `PUT` to `transfer.path` with its `Content-Length`. The file never passes through MCP, and there is no upload credential to pass on. Follow it with `get_source_intake`; once it is `REGISTERED`, admit it with `admit_initial_discovery` and `source: {kind: "intake", intakeId}`. An intake waits one hour. A file that is too large (over 1 MiB), malformed, cut short, not the expected digest, or different from what the intake already registered registers nothing and says why. External `$ref` links are never fetched; they stay visible gaps. - Read the canonical inventory: `get_discovery_generation` with `include: "inventory"` returns `{ generationId, inventoryPage }`, at most 32 KiB as a whole, small enough to read inline (pass `maxBytes`, up to 262,144, for larger pages; `admittedBytes` states the budget, and a cursor keeps it). Read the generation itself without `include`. The inventory comes as one stream: its header (section `header`) first, then every entry with its section and index, plus each section's count and `nextCursor` (pass it as `cursor`). An item too large for one page arrives as consecutive `fragment`s of its JSON text: join their `text` and parse it. The items of every page, in order, rebuild the stored inventory; HTTP serves the same pages. A missing or altered artifact is `DISCOVERY_ARTIFACT_CORRUPT`, never an empty page. - Revoke a wrong or old source: Tell your human, then call `revoke_discovery_source` with the `sourceVersionId` and your reason. It is never used again, every generation built on it leaves the current Discovery at once, and history stays readable. A repeat changes nothing. Revoking does not delete the stored document. - Erase a stored source only with your human's approval: `request_discovery_source_erasure` names the `sourceVersionId`, its current `digest` (read it with `get_discovery_source`) and why. Nothing is erased yet. Give your human the pending step's `approvalUrl`: only they decide, signed in to Dino directly, and Dino refuses the decision from you. Tell them exactly what is erased: the stored document and the inventory of every generation built on it. Their confirmation completes it, so poll `get_presentation_request`. From then on the content is never served (`DISCOVERY_CONTENT_ERASED`), and `get_discovery_source` shows `ERASURE_PENDING` until every stored object is deleted, then `ERASED`. A minimal record (digest, size, origin, admission and the audit) stays. A changed or already erased source is refused; a declined request erases nothing. ## Install Full page: https://usedino.dev/docs/install One command on macOS and Linux, no Node.js needed: `curl -fsSL https://usedino.dev/install.sh | sh` (or `wget -qO- https://usedino.dev/install.sh | sh`). It installs the standalone `dino` binary for your OS and CPU into `~/.local/bin` without sudo or prompts, and refuses to install if the binary doesn't match the release's `SHA256SUMS`. Where no binary fits (for example Alpine/musl), it falls back to `npm install -g @dino-hq/cli`, which needs Node.js 22+. Check the install with `dino --version`. Pin a version with `sh -s 1.4.0`. Options: `DINO_VERSION`, `DINO_INSTALL_DIR` (default `~/.local/bin`), `DINO_LINUX_BASELINE` (1 forces the build for Linux CPUs without AVX2). In CI, scripts and AI agents, run the pipe under pipefail and pin the version: `bash -o pipefail -c 'curl -fsSL https://usedino.dev/install.sh | sh -s 1.4.0'` (the same for the `wget` form). Without pipefail a pipe reports only its last command, so a missing or failing `curl`/`wget` makes `sh` read an empty script and exit 0 with nothing installed. Stock `ubuntu` and `debian:*-slim` images have no curl (install it with `apt-get update && apt-get install -y curl ca-certificates`). Without bash, download first and run the file: `curl -fsSLo install.sh https://usedino.dev/install.sh && sh install.sh 1.4.0`. With Node.js available you can skip installing: `npx -y @dino-hq/cli@1.4.0 `. Other ways: Homebrew, `brew install dino-hq/tap/dino` (macOS and Linux, same standalone binary); `npm install -g @dino-hq/cli` (Node.js 22+); or download a binary from https://github.com/Dino-HQ/dino/releases/latest (dino-darwin-arm64, dino-darwin-x64, dino-linux-x64, dino-linux-x64-baseline, dino-linux-arm64, dino-windows-x64.exe). Windows has no PowerShell installer yet: use npm or the .exe. On macOS use the install command rather than a browser download, because the binaries aren't notarized yet and Gatekeeper blocks browser-downloaded copies. Verify a download against `SHA256SUMS`, or its keyless Sigstore bundle with `cosign verify-blob`. After installing, `dino init` creates a `.dino.yml`, and `dino scan --endpoint ` runs a scan. No account is needed for local scans. ## Security Security covers data handling, boundaries, and how Dino behaves when it tests live endpoints. Dino is designed to avoid destructive production effects and to keep findings on your side of the boundary unless you opt into cloud workflows. Read the full security page on usedino.dev for the current posture and subprocess boundaries. ## Blog - **Welcome to the Dino blog** (welcome-to-dino-blog): This is your first Sanity-backed post on usedino.dev. Edit or delete it in Studio, then redeploy the static site. ## Changelog - **The runner settles its credential before it tests your API, and dino login signs in where you point it** (v1.4.0-credential-before-contact, 2026-10-05): A refused credential or Target Connection now stops a scan before discovery and before any test request, and discovery can use the scan's credential. dino login --api-url signs in to that API and opens your browser. dino credential set no longer takes --har. - **Dino findings in your GitHub Security tab, and an alert only closes when it was re-tested** (v1.3.0-findings-in-code-scanning, 2026-10-01): dino scan --format sarif and the GitHub Action's format: sarif put API findings into GitHub code scanning. A partial scan carries untested alerts forward instead of closing them. Also: dino credential set, and the runner reports authentication for every scan. - **dino verify tells your pipeline why it couldn't prove a result** (v1.2.2-verify-tells-you-why, 2026-09-29): dino verify ends in a declared exit code: 0 verified, 3 not proven, 5 the runner can't be verified yet, 2 the scan wasn't found. The npm package now installs with zero runtime dependencies and documents the whole CLI. - **When Dino stops, it tells you whose problem it is** (v1.2.1-exit-codes-you-can-trust, 2026-09-29): A mistake in your command or config now exits 2 or 5 with what to fix, never "Dino crashed". Tenant auth reaches every probe, a bad credential stops the scan instead of becoming a finding, and Dino reports fewer false findings. - **dino diff meets your latest scan** (v1.1.5-signed-binaries-one-snapshot-store, 2026-09-24): `dino diff` now compares against your latest scan, macOS binaries are correctly code-signed, and new versions become available only once every download is ready. - **From plan to proof** (v1.1.3-from-plan-to-proof, 2026-09-23): Dino now accounts for the full verification run: what it planned, what ran, what passed, what failed, what could not be verified, and the canonical evidence behind the verdict. - **dino init, now driven by an agent** (v1.0.7-headless-init-for-agents, 2026-08-15): Headless `dino init`: an autonomous agent or a CI job can configure Dino end to end with zero prompts, one round-trip validation, and machine-readable results. - **Accurate package metadata** (v1.0.6-package-metadata, 2026-08-15): Housekeeping: the npm package description and maintainer details now read correctly. - **Linear-time output scanning** (v1.0.4-linear-time-scanning, 2026-08-15): A hardening fix: Dino's output leak-check now runs in guaranteed linear time, closing a potential ReDoS flagged by CodeQL. - **Output you can pipe, diff, and trust** (v1.0.3-trustworthy-output, 2026-08-15): Every command now separates the verdict from the noise: clean JSON on stdout, honest exit codes, and a permanent contract that keeps Dino's output machine-readable. - **Onboarding, OAuth2, and REST everywhere** (v1.0.2-onboarding-oauth2-and-rest, 2026-08-08): A one-step dino init with authenticated local tests, OAuth2 client-credentials, and full REST coverage across docs, watch, and change tracking. - **Clean scan output** (v1.0.1-clean-scan-output, 2026-08-07): dino scan now prints only your report. Every spinner, notice, and engine log moved to stderr, so piping and redirecting a scan finally do exactly what you expect. - **Dino CLI 1.0** (v1.0.0-cli-1-0, 2026-08-06): The Dino CLI is now stable and generally available, with a hardened dino login and a committed versioning contract you can pin in CI. - **Documentation Refresh** (v0.4.5-docs-and-infrastructure, 2026-04-19): The docs catch up to REST: docs.usedino.dev and every README rewritten, plus the v0.4.1–v0.4.4 release-pipeline hardening rolled up. - **REST API Scanning** (v0.4.0-rest-api-scanning, 2026-04-18): Dino now scans REST end to end: OpenAPI discovery, 19 fuzz strategies across 6 attack surfaces, response validation, and a real --fail-on-high CI gate. - **CLI UX Patch** (v0.3.1-cli-ux-patch, 2026-04-16): Fewer mystery failures: dino init warns before a bad URL, and scan timeouts now tell you what to do. Plus the groundwork for REST. - **Rich Terminal UI** (v0.3.0-rich-terminal-ui, 2026-04-12): An Ink-powered terminal UI with a real design system, an ESM bundle a quarter of the size, and a tag-based release pipeline. Node 22 required. - **Zero-Config Scanning** (v0.2.0-zero-config-scanning, 2026-04-06): Point Dino at an endpoint and it just works: resilient introspection, operations generated from the live schema, and clean, pipeable output. - **Socket.dev remediation** (v0.1.1-socket-remediation, 2026-04-03): A security housekeeping release: four Socket.dev supply-chain findings remediated, and npm audit back to clean. - **First public release** (v0.1.0-first-release, 2026-04-01): Dino is on npm as @dino-hq/cli. Install it globally, point it at a GraphQL endpoint, and get a real quality report in your terminal.