---
title: "CLI Shield Commands"
description: "Manage Edge Shield bot-protection widgets from the command line."
url: https://edge.network/docs/cli/shield/
---

# CLI Shield Commands

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](https://edge.network/docs/shield/siteverify) 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](https://edge.network/docs/shield/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 |

## See Also

[Shield Docs Embed the widget and validate tokens](https://edge.network/docs/shield/getting-started) [Widget Modes Managed, non-interactive, and invisible](https://edge.network/docs/shield/widget-modes)
[Back to Docs](https://edge.network/docs) [Need help?](https://edge.network/support)