Oopsie CLI

Install

curl -fsSL https://raw.githubusercontent.com/theinventor/Oopsie/main/cli/oopsie -o oopsie
chmod +x oopsie
sudo mv oopsie /usr/local/bin/  # optional: add to PATH

Setup

Add a connection — a server URL plus an API key. Use your User API Key (from the Account page) to reach every project with one key:

oopsie config add prod --server https://your-oopsie-instance.com --key YOUR_USER_API_KEY

Or use a Project Key (from project settings) if you only need one project:

oopsie config add myproject --server https://your-oopsie-instance.com --key YOUR_PROJECT_KEY

With a user key, pin the project you work with most so you don't have to pass --project every time:

oopsie config set-project myapp

Everyday Commands

Command	Description
oopsie whoami	Show current connection, auth type, and project access
oopsie projects	List all projects you can access (user key) or the one project (project key)
oopsie project	Summary of the active project (pinned or --project)
oopsie project create "New App" --if-missing	Create a uniquely named project with a user key, or reuse one exact match, and print the project key for client apps
oopsie project update <id> --name "Renamed App"	Rename a project with a user key
oopsie project disable <id>	Disable new exception ingest while keeping historical errors browsable
oopsie project enable <id>	Re-enable exception ingest for a disabled project
oopsie errors	List error groups for the active project
oopsie errors --status resolved	Filter by status (unresolved/resolved/ignored)
oopsie errors --workflow-state blocked	Filter by agent workflow state
oopsie show <id>	Show error group details and recent occurrences
oopsie state <id> in_progress --note "..."	Set workflow state without resolving or ignoring
oopsie note <id> --body "..."	Add investigation evidence
oopsie resolve <id>	Mark as resolved
oopsie ignore <id>	Archive (ignore) an error group
oopsie reopen <id>	Reopen a resolved or ignored error group
oopsie webhooks	List webhook notification rules (destinations masked)
oopsie webhook setup --input-json -	Create or reuse a webhook; secrets on stdin, never printed
oopsie webhook test <id>	Send a connectivity probe to a stored webhook

Global Flags

Flag	Description
-p, --project <name>	Scope to a specific project for this command (overrides pinned default)
-c, --connection <name>	Use a non-default connection
--json	Machine-readable envelope on webhook setup/test/list and version

oopsie errors --project myapp       # one-off override
oopsie errors -c staging -p myapp   # different server, specific project

Multiple Connections

Add connections for each server/environment. config use picks the default.

oopsie config add prod    --server https://oopsie.example.com         --key USER_KEY
oopsie config add staging --server https://staging.oopsie.example.com --key USER_KEY
oopsie config use prod
oopsie config list

API Reference

The CLI talks to these JSON API endpoints (Bearer token auth):

Method	Endpoint	Description
GET	/api/v1/project	One project (project key) or all accessible projects (user key)
POST	/api/v1/projects	Create a project with a user key and return its project key
PATCH	/api/v1/projects/:id	Rename a project with a user key
PATCH	/api/v1/projects/:id/disable	Disable new exception ingest for a project
PATCH	/api/v1/projects/:id/enable	Re-enable exception ingest for a project
GET	/api/v1/error_groups	List error groups (?status=, ?workflow_state=, ?limit=, ?offset=)
GET	/api/v1/error_groups/:id	Error group details + occurrences + activity
PATCH	/api/v1/error_groups/:id/workflow_state	Set workflow state with optional note
POST	/api/v1/error_groups/:id/notes	Add investigation note
PATCH	/api/v1/error_groups/:id/resolve	Mark resolved
PATCH	/api/v1/error_groups/:id/ignore	Archive (ignore)
PATCH	/api/v1/error_groups/:id/unresolve	Reopen
GET	/api/v1/notification_rules	List notification rules (destinations masked)
POST	/api/v1/notification_rules/setup_webhook	Idempotent webhook create
POST	/api/v1/notification_rules/:id/test	Connectivity probe for a stored webhook
POST	/mcp	Remote MCP (Bearer API key) for ChatGPT and Grok

All endpoints require Authorization: Bearer YOUR_KEY. Project keys can report exceptions and manage error groups for one project. User keys can list, create, rename, disable, and enable projects. When calling project-scoped endpoints with a User API Key, include project_id as a query param or X-Project-Id as a header.

Remote MCP (ChatGPT, Grok)

Hosted clients cannot spawn oopsie-mcp. Point them at https://your-oopsie-instance.com/mcp with your User API key as a Bearer token. Pass project (name or id) on tool calls unless you authenticate with a project key.

# Grok CLI
grok mcp add --transport http oopsie https://your-oopsie-instance.com/mcp \
  --header "Authorization: Bearer ${OOPSIE_API_KEY}"

# ChatGPT: Settings → Apps → Developer mode → Create
# Connector URL: https://your-oopsie-instance.com/mcp
# Auth: Token, paste your User API key from the Account page

MCP

Pair the CLI with oopsie-mcp so a local agent (Cursor, Claude Code) can set up and test webhooks over stdio. The adapter shells oopsie --json; it never returns destinations or header values.

curl -fsSL https://raw.githubusercontent.com/theinventor/Oopsie/main/cli/oopsie-mcp -o oopsie-mcp
chmod +x oopsie-mcp
sudo mv oopsie-mcp /usr/local/bin/

# Cursor / Claude Desktop mcp.json
{
  "mcpServers": {
    "oopsie": {
      "command": "oopsie-mcp",
      "env": { "OOPSIE_BIN": "/usr/local/bin/oopsie" }
    }
  }
}

Agent Triage Flow

Use workflow state for coordination and lifecycle status for truth. Agents should set looking or in_progress before work, use blocked when external input is needed, add evidence with oopsie note, and resolve or ignore only when the note trail explains why.

oopsie state 42 looking --note "Reading recent occurrences"
oopsie note 42 --body "Reproduced locally with account 123"
oopsie state 42 ready_to_resolve --note "Fix deployed and verified"
oopsie resolve 42 --note "No new occurrences after deploy"