Documentation

CLI

Install Guardy, scaffold agent integrations, and inspect sessions from a terminal.

The Guardy CLI ships with @guardy/sdk as the guardy binary. It is designed for humans and agents: local setup, scriptable inspection, and CI checks all use API-key auth instead of browser login.

Install

From the root of an agent repo:

curl -fsSL https://raw.githubusercontent.com/guardydev/Guardy/main/scripts/install.sh | bash

The installer bootstraps the CLI through npm, installs the right SDK package for the project, and writes safe example files without committing a real API key.

Authentication

Agents should use API keys from organization settings:

export GUARDY_API_KEY=guardy_live_xxx

For local human use, you can save the key once:

guardy login --api-key guardy_live_xxx

The CLI resolves credentials in this order:

--api-key
GUARDY_API_KEY
~/.guardy/config.json

Use --api-url or GUARDY_API_URL for self-hosted or local API targets.

Setup Commands

# Install the SDK and scaffold example integration files
guardy install

# Preview without changing files
guardy install --dry-run

# Scaffold examples only
guardy init

# Force language detection when a repo is ambiguous
guardy init --language python
guardy init --language typescript

Generated examples use placeholder API keys, so they are safe to commit as references.

Sessions

# List recent sessions
guardy sessions list

# Filter by time, status, or local agent name
guardy sessions list --last 7d --status failed --agent support

# Print JSON for scripts and agents
guardy sessions list --json

# Fetch one session and its events
guardy sessions get <session-id>

# Fetch a session without events
guardy sessions get <session-id> --no-events

Events

# List all events for a session
guardy events list <session-id>

# Filter event type
guardy events list <session-id> --type tool_call

# Machine-readable output
guardy events list <session-id> --json

Signals And Diagnosis

# List detected signals
guardy signals list --last 30d

# Filter signal type or source
guardy signals list --type negative --source heuristic

# Diagnose a failed session from its event timeline
guardy diagnose <session-id>

CI Gates

Use evaluate in scripts to fail a build when an experiment regresses:

guardy evaluate <experiment-id> --min-score 80 --max-regression 5

For agent automation, prefer JSON:

guardy evaluate <experiment-id> --min-score 80 --json

Reserved Commands

These commands are intentionally present but guarded until the backing APIs are public:

guardy clusters
guardy fix <session-id>
guardy replay <session-id>