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 <publicId> <environmentId>
        │ (pairs this machine once)
        ▼
CLI stores { publicId, environmentId } 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 login command from Dashboard → Settings → Dev environments (publicId + environmentId).
One environment binds to one machine until you disconnect it in the dashboard.
Credentials file holds only those IDs - no tokens or passwords (~/.config/trivuedev/credentials.json on Linux).

Logout vs disconnect

trivuedev logout: Clears the local credentials file only.
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

# Pin a version
curl -fsSL https://raw.githubusercontent.com/orashus/trivuedev/main/install.sh \
  | TRIVUEDEV_VERSION=v1.0.1 sh

# 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 login command, pair once, then inspect any local URL.

Quick start

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

# From Dashboard → Settings → Dev environments
trivuedev login lu_… de_…

trivuedev whoami
trivuedev http://localhost:3000
trivuedev http://127.0.0.1:3000 --json
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_…

Commands

trivuedev login <publicId> <environmentId>
Pair this machine to a Dev Environment. Copy the full command from Dashboard → Settings → Dev environments.
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).
trivuedev logout
Clear local credentials only. Does not disconnect the environment on the server.
trivuedev --version / --help
Print version or usage.

Environment

TRIVUE_API_URL

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

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
Body: { "url": "https://…" }

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.

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 or missing url field.
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 or missing url field.
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.

Agent and editor integrations are on the roadmap - MCP server, VS Code extension, and Chrome extension. Back to home.