CLI

Shield Commands

Create and manage Edge Shield widgets — free, privacy-first bot protection — without leaving your terminal.

Widgets

List Widgets

$ edge shield list
ID           NAME            SITEKEY                              MODE       AGENTS     HOSTNAMES         CREATED
wgt-abc123   Contact form    es_6206c6fdb43e7a3cb948507e6f3e5a11  managed    allow      example.com       2026-03-01
wgt-def456   Signup          es_9f2a1b8c7d6e5f4a3b2c1d0e9f8a7b6c  invisible  challenge  any               2026-04-12

Create a Widget

$ edge shield create --name "Contact form" --hostname example.com

Creating widget... done

✓ Created widget Contact form (wgt-abc123)

Sitekey:       es_6206c6fdb43e7a3cb948507e6f3e5a11
Secret:        ss_4f8e2a1b9c7d6e5f4a3b2c1d0e9f8a7b
Mode:          managed
Agent Policy:  allow
Hostnames:     example.com

! Store the secret securely — it will not be shown again.

Embed on your page:
  <script src="https://shield.edge.network/api.js" defer></script>
  <div class="edge-shield" data-sitekey="es_6206c6fdb43e7a3cb948507e6f3e5a11"></div>

The secret is shown only once

Store it as a server-side environment variable immediately. It's needed for server-side validation and cannot be retrieved later — if it's lost, create a new widget.

Get Widget Details

$ edge shield get wgt-abc123
ID:            wgt-abc123
Name:          Contact form
Sitekey:       es_6206c6fdb43e7a3cb948507e6f3e5a11
Secret:        ss_4f8e...
Mode:          managed
Agent Policy:  allow
Hostnames:     example.com
Created:       2026-03-01

Update a Widget

# Switch to invisible mode
edge shield update wgt-abc123 --mode invisible

# Replace the hostname allowlist
edge shield update wgt-abc123 --hostname example.com --hostname www.example.com

# Challenge verified AI agents instead of allowing them
edge shield update wgt-abc123 --agent-policy challenge

# Rename
edge shield update wgt-abc123 --name "Contact form (prod)"

Revoke a Widget

# Revoke with confirmation
edge shield delete wgt-abc123

# Revoke without confirmation
edge shield delete wgt-abc123 --force

Revocation is immediate — the sitekey and secret stop working, and any pages still embedding the widget will fail verification.

Traffic Stats

Challenge volume, solve rates, humanity scores, server-side verifications, and blocked replays. Defaults to the last 24 hours; use --hours for up to 30 days.

$ edge shield stats wgt-abc123 --hours 168
  Last 168 hours:

Challenges issued:     14,382
Challenges solved:     9,041 (62.9%)
Interactive shown:     412 (2.9%)
Avg humanity score:    78/100
Verified submissions:  1,204
Failed verifications:  38
Replays blocked:       17
Verified agents:       93

Shield Examiner

Run AI-powered analysis of a widget's aggregate traffic. Flags bot pressure, replay abuse, and calibration issues, and recommends configuration changes — the same Examiner available in the control panel.

# Run AI-powered traffic examination
edge shield examine wgt-abc123

# View the last examination result
edge shield examine-last wgt-abc123

# Output as JSON
edge shield examine wgt-abc123 --output json

Examinations take up to 45 seconds. Results are saved and can be retrieved with examine-last.

Common Flags

Flag	Description
--name	Widget name
--hostname	Allowed hostname (repeatable). Empty = any hostname
--mode	Widget mode: managed, non-interactive, invisible
--agent-policy	Verified-agents policy: allow, challenge, block
--hours	Stats window in hours (max 720)
--force	Skip delete confirmation