---
title: "Shield commands"
description: "Edge CLI Shield command reference: create, update and revoke bot-protection widgets, view traffic stats and run the AI-powered Shield Examiner."
url: "https://edge.network/docs/cli/shield"
section: "CLI"
---

# Shield commands

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

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

> [!WARNING]
> **The secret is shown only once.** Store it as a server-side environment variable immediately. It's needed for [server-side validation](/docs/shield/siteverify) and cannot be retrieved later. If it's lost, create a new widget.

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

```bash
# 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

```bash
# 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](/docs/shield/examiner) that is available in the console.

```bash
# 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

- [Shield docs](/docs/shield/getting-started) — Embed the widget and validate tokens
- [Widget modes](/docs/shield/widget-modes) — Managed, non-interactive and invisible