Using Spectra

Install

Download the macOS build from the home page. Drag Spectra.app into /Applications. First launch needs Right-click, then Open to bypass Gatekeeper while the build is unsigned during beta.

Requirements: macOS 12 or later. Apple Silicon and Intel builds ship separately.

First run

1. Open Spectra. The welcome screen offers two paths: open a recent project or add a new one.
2. Add a project by pointing at your Laravel codebase folder (the one with artisan at the root).
3. Spectra runs php artisan route:list --json, reflects your FormRequest classes, and builds an endpoint tree.
4. Pick any endpoint from the sidebar and hit Execute.

Core concepts

Project

A pointer to a codebase folder. Carries its own base URL, drivers, environments, accounts, and collections.

Driver

The framework adapter. Today: Laravel. Drivers stay behind a clean interface, so no framework code leaks into the core.

Endpoint

A route discovered from your codebase. Has method, URI, handler, middleware, and any attached FormRequest.

Snapshot

A response pinned as the source of truth. Future executions diff against it.

Add a project

From the project switcher (top-left), pick Add project. Three fields:

• Folder. The repo root. Spectra needs read access to run artisan and walk app/Http/Requests.
• Driver. Laravel during beta. More drivers come online as they ship.
• Base URL. Defaults to your Herd .test domain if detected. Override per environment later.

Pick a driver

The driver decides how Spectra introspects your routes and validation. The Laravel driver:

• Spawns php artisan route:list --json on demand.
• Parses FormRequest::rules() via reflection.
• Detects middleware groups (auth:sanctum, throttle, etc).
• Reads Sanctum-style token tables when wired through the Accounts panel.

If a route is registered via a closure with no controller, it still shows up. Spectra falls back to whatever metadata the framework exposes.

Switch projects

Top-left dropdown lists every project you've added. Cmd+P opens the command palette with project search built in. Switching is instant: state, pinned routes, and history are per-project.

API Inspector

The main workspace. Three panes:

• Left. Endpoint tree. Filter, expand by group, star to pin.
• Center. Request panel. Body, Params, Headers, Cookies tabs.
• Right. Response panel. JSON, Raw, Headers, History tabs.

Open it with Cmd+2 from anywhere.

Request panel

Body

JSON or Form mode. JSON mode ships with a CodeMirror editor, syntax highlighting, and validation. Form mode mirrors your FormRequest fields when one is detected.

Params

Query string editor. Toggle keys on and off, reorder, paste a full URL to auto-split.

Headers

Per-request overrides. Defaults come from the active environment.

Cookies

Persist per environment. Cleared on environment switch.

Hit Execute (bottom bar) or press Enter while focused on the request.

Response panel

Top-right shows status, latency, and size. Tabs:

• JSON. Pretty-printed with syntax highlight. Click any value to copy.
• Raw. Untouched body.
• Headers. Server-returned headers, including CORS and rate-limit info.
• History. Every prior call for this endpoint, with timestamps.

The Copy button up top grabs the body. Snapshot pins the current response.

Pinning routes

Star any endpoint to move it into the Pinned group at the top of the sidebar. Pinned routes survive project switches, app restarts, and route re-scans. Use them for the 5 to 10 endpoints you actually hit every day.

Form Requests

When an endpoint has a FormRequest attached, Spectra surfaces it as a badge above the body editor. The badge shows:

• The FormRequest class name.
• How many fields are required.
• Whether the current body matches.

Switch to Form mode to fill fields with type hints (string, int, enum, file) drawn from the rules. Validation runs locally before the request fires.

Environments

Each project carries multiple environments (local, staging, production). An environment defines:

• Base URL.
• Default headers (Authorization, Accept, X-Tenant).
• Variables you reference in request bodies as {{name}}.

Top bar shows the active environment. Switching reloads variables instantly. Secrets live in the macOS Keychain, not the project file.

Accounts and auth

The Accounts page (Cmd+5 in older builds, sidebar key icon) stores credentials per environment. Spectra supports:

• Bearer tokens (Sanctum, Passport, custom).
• Basic auth.
• Cookie-based session auth (with automatic CSRF token handshake).
• API keys via header or query.

Pick an account from the top bar to apply it to the current session. Token values never write to project JSON files. Keychain only.

Collections

Group endpoints by feature, sprint, or test scenario. Collections are independent of the auto-discovered tree, so you can hand-curate a "smoke test" set or share a "billing endpoints" group with a teammate.

Collections are plain JSON files inside the project folder. Commit them to git for sharing.

History

Every execution lands in history with timestamp, status, latency, and the exact request body. Filter by endpoint, status, or date. Click any entry to replay it, or to load it into the request panel for tweaking.

Snapshots and diff

Pin a response as the canonical answer. Next time the endpoint runs, Spectra diffs the new response against the snapshot:

• Green: matches.
• Yellow: structurally same, values differ (timestamps, IDs).
• Red: schema break.

Configure which fields are "noisy" (and so ignored) per snapshot. Snapshots live in .spectra/snapshots/ inside your project. Commit them.

Capture mode

Point your local app at Spectra's local proxy port. Every request flowing through gets recorded and offered for save as an endpoint, with body, headers, and cookies preserved. The fastest way to bootstrap coverage on a legacy API.

Capture writes to history first, so nothing commits to a collection until you say so.

Mock server

Spin up a local mock server that replays your saved snapshots as if it were the real API. Useful for frontend work when the backend isn't deployed, or for offline development.

Match rules cover method, path (with params), and headers. Default port is 4710.

Scratch pad

Cmd+4 opens a stateless request editor. No endpoint binding, no history. Use it for one-off curls, webhook tests, or quick external API pokes without polluting your project history.

Command palette

Cmd+K opens the palette. From there you can jump to any page, search endpoints across all projects, switch project, switch environment, or fire any registered action. Built with cmdk, so fuzzy search is sharp.

Keyboard shortcuts

Settings

Cmd+, opens Settings. Tabs cover:

• Appearance. Theme, font, density. Dark by default.
• Database. Where Spectra keeps its local SQLite store. Export, import, encrypt.
• Network. Proxy, certificate trust, request timeouts.
• Drivers. Per-driver config (PHP binary path, artisan flags).

Files and storage

• ~/Library/Application Support/Spectra/. SQLite store and app state.
• .spectra/ at your project root. Collections, snapshots, environment templates (no secrets).
• macOS Keychain. Tokens, passwords, API keys. Never plaintext.

Project files are plain JSON, designed to be committed. The Keychain split keeps git history clean.

Troubleshooting

Routes don't appear after adding a project.

Spectra needs php on PATH. Check Settings, Drivers, PHP binary path. Herd users usually point at ~/.config/herd/bin/php.

FormRequest fields show up empty.

Spectra reflects via a one-shot artisan command. If your FormRequest constructor has heavy deps, reflection may fail. Open an issue with the class name.

Snapshot keeps marking timestamps as a diff.

Add the field path to the snapshot's noisy-fields list. Right-click the field in the JSON viewer, then "Ignore in snapshots."

Bearer token doesn't apply.

Check that the account is selected in the top bar. Token-less accounts pin the icon as gray.