Setup guide

Connect your machine to Observal with two commands. It takes about two minutes and does not need Python or Docker.

1. Run the two commands for your OS

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/Observal/Observal/main/install.sh | bash
observal auth login --server https://internal.observal.io

Windows (in PowerShell, not Command Prompt)

irm https://raw.githubusercontent.com/Observal/Observal/main/install.ps1 | iex
observal auth login --server https://internal.observal.io

The first command installs the observal CLI. The second connects it to the server.

Login method: pick the one your team uses. If unsure, choose Web sign-in and approve the code in your browser.
Fix all warnings? (configures telemetry and installs AI skills for detected harnesses) [Y/n]: answer Y (or press Enter). This is the step that instruments your coding tools. For each one Observal finds (Claude Code, Cursor, Kiro, Codex, Copilot, OpenCode, Pi, and others), it:
- adds the hooks that send your sessions to Observal
- installs the Observal skills, so your coding agent can search and use approved agents, MCP servers, and skills
If you answer n, nothing is instrumented and your sessions won’t show up. You can fix that later with observal doctor patch --all-harnesses.
Restart any coding tool that was open during setup so it picks up the changes.

observal auth whoami

Then open internal.observal.io. Your sessions appear under Traces after your next coding session.

Problem	Fix
`observal: command not found`	Open a new terminal window. On macOS/Linux, also check that `/usr/local/bin` is on your `PATH`.
Intel Mac: download fails	There is no standalone binary for Intel Macs yet. Run `uv tool install observal-cli` instead of the first command.
PowerShell refuses to run `irm ... \| iex`	Run `Set-ExecutionPolicy -Scope Process Bypass` in the same window, then retry.
Login can’t reach the server	Check that you’re on the VPN, then run `curl https://internal.observal.io/health`.
Answered n to the prompt, or added a new coding tool later	Run `observal doctor patch --all-harnesses`.

To upgrade later, run observal self upgrade.