Skip to content
CLI · Shield commands

CLI

Shield commands

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

On this page5 sections

Widgets#

List widgets#

Text
$ 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#

Text
$ 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>

Get widget details#

Text
$ 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#

Terminal
# 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#

Terminal
# 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#

Shows 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.

Text
$ 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. It flags bot pressure, replay abuse and calibration issues, and recommends configuration changes. It is the same Examiner that is available in the console.

Terminal
# 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

Next steps

Something unclear or out of date? Tell us

View as Markdown Get support