Docs

API & Dev Mode

Inspect public URLs over HTTP, or use the trivuedev CLI to debug localhost without Trivue ever fetching your machine. Same inspection engine either way.

Architecture

How Dev Mode connects

Production Trivue blocks localhost and private addresses on /api/inspect (SSRF protection). Dev Mode keeps that rule intact: your laptop fetches the page; Trivue only receives the HTML.

Request flow

Dashboard → create Dev Environment
        │
trivuedev login <secret>
        │ (pairs this machine once)
        ▼
CLI stores { secret } locally
        │
trivuedev http://localhost:3000
        │ 1. CLI fetches localhost on your machine
        │ 2. CLI submits the HTML to Trivue
        ▼
Trivue inspects the HTML
        → ephemeral /local-preview/lp_… (1 hour)

Pairing (not passwords)

Copy the environment secret from Dashboard → Developer → View and run trivuedev login <secret>.
One environment binds to one machine until you disconnect it in the dashboard or run trivuedev logout.
Credentials file holds only the secret (~/.config/trivuedev/credentials.json on Linux).

Logout vs disconnect

trivuedev logout: Unbinds the machine on the server, then clears the local credentials file.
Dashboard → Disconnect: Clears the server binding so another machine can pair that environment.

Loopback only in v1: localhost, 127.0.0.1, ::1. Not a LAN proxy. Previews expire after one hour (rate-limited per environment).

trivuedev

Install the CLI

Binaries ship from the public distribution repo github.com/orashus/trivuedev (installers + releases only - source stays private).

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/orashus/trivuedev/main/install.sh | sh

macOS / Linux # Pin a version

curl -fsSL https://raw.githubusercontent.com/orashus/trivuedev/main/install.sh | TRIVUEDEV_VERSION=vX.Y.Z sh

macOS / Linux # Custom install dir (default: ~/.local/bin)

TRIVUEDEV_INSTALL_DIR="$HOME/.local/bin" sh install.sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/orashus/trivuedev/main/install.ps1 | iex

Prefer to inspect the script first: curl -fsSL …/install.sh -o install.sh && less install.sh && sh install.sh. Releases and checksums: Releases.

trivuedev

CLI usage

Create a Dev Environment in the dashboard, copy the secret from View, pair once, then inspect local URLs. Public URLs work without pairing unless you pass --save.

Quick start

# Optional: point at a local Trivue instance
export TRIVUE_API_URL=http://localhost:3000

# From Dashboard → Developer → View
trivuedev login api_…

trivuedev whoami
trivuedev http://localhost:3000
trivuedev http://127.0.0.1:3000 --json
trivuedev https://orashus.com
trivuedev https://orashus.com --save --json
trivuedev mcp
trivuedev logout

Human output (example)

$ trivuedev http://localhost:3000
✓ Fetched http://localhost:3000
✓ Trivue inspection complete

Preview (expires in ~1h):
https://trivue.orashus.com/local-preview/lp_…

Public URL (example)

$ trivuedev https://orashus.com
✓ Trivue inspection complete
Score: 87/100

$ trivuedev https://orashus.com --save
✓ Trivue inspection complete
Score: 87/100

Preview:
https://trivue.orashus.com/local-preview/lp_…

Commands

trivuedev login <secret>
Pair this machine to a Dev Environment. Copy the secret from Dashboard → Developer → View.
trivuedev whoami
Confirm the paired account / environment is still valid on this machine.
trivuedev <localhost-url> [--json]
Fetch loopback HTML locally, submit it to Trivue, print the ephemeral preview URL (and JSON with --json). Always saves a LocalPreview.
trivuedev <public-url> [--json] [--save]
POST /api/inspect (Trivue fetches the page). Default does not persist. --save requires pairing and creates a LocalPreview (data.url).
trivuedev mcp
Local MCP stdio (inspect_local_url + inspect_remote_url). Uses TRIVUE_API_KEY if set, otherwise credentials.json. JSON-RPC on stdout only - no help banners.
trivuedev logout
POST /api/cli/logout to unbind the machine, then clear the local credentials file.
trivuedev --version / --help
Print version or usage.

Environment

TRIVUE_API_URL

API base URL. Default https://trivue.orashus.com.

TRIVUE_API_KEY

Optional environment secret. If set, the CLI and local MCP use it instead of credentials.json.

Exit codes

0Success
1General error
2Invalid arguments
3Auth / pairing failure
4Local fetch failed
5Trivue API error

HTTP API

Inspect any public URL

The same pipeline that powers the web UI. Send a public http or https URL and receive score, diagnostics, platform previews, and image analysis. Loopback and private addresses are always blocked -use Dev Mode for those.

Endpoint

POST https://trivue.orashus.com/api/inspect

Accept: application/json
Query: save (optional; presence persists a LocalPreview)
Body: { "url": "https://…" }; with ?save also usedBy (secret is the x-trivue-api-key header)

?save persists a LocalPreview and adds data.url. Requires x-trivue-dev: true and x-trivue-api-key. The web UI does not set these flags.

Related routes

/r/[id] -public frozen report snapshot
/r/live?url=… -live inspection page (refreshes on each load)
/local-preview/[id] -ephemeral Dev Mode local preview

Response envelope

All responses use the same shape: message, status, and data.

fetch
Requested vs final URL, HTTP status, content type, HTML length.
rawMetadata
Standard, Open Graph, and Twitter tags as extracted from HTML.
normalizedMetadata
Resolved title, description, image, and fallbacks with source tracking.
diagnostics
Findings grouped by severity with suggested fixes.
trivueScore
Score (0-100), category, and deduction breakdown.
platformPreviews
Simulated previews for X, Facebook, LinkedIn, and others.
platformCompatibility
Per-platform compatibility summary and warnings.
imageAnalysis
Live social image fetch - dimensions, format, reachability.
durationMs
End-to-end processing time in milliseconds.
url
Present only when ?save is set: the LocalPreview page (/local-preview/lp_…).

curl

Pipe to jq to pretty-print JSON

curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/page"}' \
  https://trivue.orashus.com/api/inspect

Success (200)

{
  "message": "Inspection complete.",
  "status": 200,
  "data": {
    "fetch": { "finalUrl": "https://example.com/page", "status": 200, … },
    "trivueScore": { "score": 87, "category": { … }, … },
    "diagnostics": [ … ],
    "platformPreviews": [ … ],
    "imageAnalysis": { … },
    "durationMs": 1240
  }
}

Error (4xx / 5xx)

{
  "message": "Enter a valid http or https URL.",
  "status": 400,
  "data": { "code": "INVALID_INPUT" }
}

Error codes

INVALID_INPUT
HTTP 400
Malformed JSON, missing url, or invalid save payload.
FORBIDDEN
HTTP 403
?save without x-trivue-dev: true.
INVALID_URL
HTTP 400
URL failed client-side validation.
BLOCKED_HOST / BLOCKED_ADDRESS
HTTP 403
SSRF protection blocked the target (including localhost and private addresses).
UNSUPPORTED_PROTOCOL
HTTP 400
Only http and https are allowed.
TIMEOUT
HTTP 504
Remote page did not respond in time.
RESPONSE_TOO_LARGE
HTTP 413
Page or image exceeded size limits.
UNSUPPORTED_CONTENT_TYPE
HTTP 415
Target is not an HTML page.
HTTP_ERROR / FETCH_FAILED
HTTP 502
Remote server error or unreachable URL.
INTERNAL_ERROR
HTTP 500
Unexpected server error.

Code	HTTP	Meaning
INVALID_INPUT	400	Malformed JSON, missing url, or invalid save payload.
FORBIDDEN	403	?save without x-trivue-dev: true.
INVALID_URL	400	URL failed client-side validation.
BLOCKED_HOST / BLOCKED_ADDRESS	403	SSRF protection blocked the target (including localhost and private addresses).
UNSUPPORTED_PROTOCOL	400	Only http and https are allowed.
TIMEOUT	504	Remote page did not respond in time.
RESPONSE_TOO_LARGE	413	Page or image exceeded size limits.
UNSUPPORTED_CONTENT_TYPE	415	Target is not an HTML page.
HTTP_ERROR / FETCH_FAILED	502	Remote server error or unreachable URL.
INTERNAL_ERROR	500	Unexpected server error.

The MCP server uses the same engine (hosted MCP is public URLs only; the local Dev inspector handles public URLs and localhost). Copy the environment secret from Dashboard → Developer. VS Code and Chrome extensions are on the roadmap. Back to home.