vigocli envoys

Manage enrolled envoys (managed nodes).

Subcommands

Usage

vigocli envoys [subcommand] [flags]

list

List active (non-revoked) envoys with their status. Pass --all to include revoked envoys.

vigocli envoys list
vigocli envoys list --all   # include revoked

Example output

ID          HOSTNAME              IP             ENROLLED           LAST SEEN          STATUS
a1b2c3d4    web-01.example.com    10.0.1.10      2026-03-01 08:00   2026-03-13 12:30   active
e5f6g7h8    db-01.internal.net    10.0.2.20      2026-03-02 09:15   2026-03-13 12:28   active

show

Show detailed information for a specific envoy, including compliance status and pending secret rotations. Accepts a full UUID, short UUID prefix, or hostname.

vigocli envoys show <id-or-hostname>

Example

vigocli envoys show web-01.example.com
vigocli envoys show a1b2c3d4

ID:         a1b2c3d4
Hostname:   web-01.example.com
IP:         10.0.1.10
Enrolled:   2026-03-01 08:00
Last Seen:  2026-03-13 12:30
Status:     active
Compliance: compliant

revoke

Revoke an enrolled envoy. The envoy will receive an error on its next check-in and cannot re-enroll with the same UUID.

vigocli envoys revoke <id>

Example

vigocli envoys revoke a1b2c3d4

Revoked envoy a1b2c3d4

delete

Permanently delete a envoy and all its associated history.

vigocli envoys delete <id>

Example

vigocli envoys delete a1b2c3d4

Deleted envoy a1b2c3d4

traits

View collected traits for a envoy by hostname. Optionally drill into a specific trait using a dot-separated path.

vigocli envoys traits <hostname> [dot.path]

Examples

View all traits

vigocli envoys traits web-01.example.com

{
  "hostname": "web-01.example.com",
  "collected_at": "2026-03-13T12:30:00Z",
  "traits": {
    "os": {
      "distro": "ubuntu",
      "version": "24.04",
      "family": "debian"
    },
    "memory": {
      "total": 8589934592,
      "percent": 62.5
    }
  }
}

View a specific trait

vigocli envoys traits web-01.example.com os.distro

ubuntu

tag

Set tags on a envoy for targeting.

vigocli envoys tag <id> <tag1,tag2,...>

Example

vigocli envoys tag a1b2c3d4 webserver,production

Tags set: webserver, production

Tags replace all existing tags. To add to existing tags, include the old ones.

untag

Remove specific tags from a envoy.

vigocli envoys untag <id> <tag1,tag2,...>

Example

vigocli envoys untag a1b2c3d4 staging

Tags updated: webserver, production

maintenance

Set or clear maintenance mode for a envoy. While in maintenance, the envoy receives an empty policy on check-in (skips convergence) but still reports traits.

vigocli envoys maintenance <id> --until <RFC3339>
vigocli envoys maintenance <id> --clear

Flags

Example

# Set maintenance until 6 AM tomorrow
vigocli envoys maintenance a1b2c3d4 --until 2026-03-14T06:00:00Z

# Clear maintenance
vigocli envoys maintenance a1b2c3d4 --clear

purge

Delete stale duplicate envoys. When a machine is rebuilt and re-enrolled with the same hostname, the old entry remains with a different UUID. purge finds all hostnames with multiple entries and deletes all but the most recently seen one.

Revoked entries always lose to active ones. Among entries with the same status, the most recent last_seen timestamp wins.

vigocli envoys purge

Flags

Example

# Preview what would be deleted
vigocli envoys purge --dry-run

# Purge stale duplicates (prompts for confirmation)
vigocli envoys purge

ID          HOSTNAME              IP           LAST SEEN         STATUS
e6ff73f8    raspberry             192.168.1.78 2026-03-15 12:17  active
a1b2c3d4    raspberry             192.168.1.78 2026-03-14 09:30  revoked

2 duplicate envoy(s) will be deleted.
Purge these envoys? [y/N] y
  deleted e6ff73f8 (raspberry)
  deleted a1b2c3d4 (raspberry)
Purged 2 stale envoy(s).

push

Force a envoy to check in and converge immediately, without waiting for its next polling interval. Sets a force-update flag on the server that the agent picks up on its next poll.

# Push a single envoy
vigocli envoys push <hostname-or-uuid>

# Push all active envoys
vigocli envoys push --all

Flags

Example

vigocli envoys push web-01.example.com

OK Force update queued for web-01.example.com

rebootstrap

Signal envoys to download the latest agent binary and restart on their next check-in. No SSH required — the server sets a force_update flag that the agent picks up during its normal polling cycle.

# Update specific envoys
vigocli envoys rebootstrap plex raspberry

# Update all active envoys
vigocli envoys rebootstrap --all

The agent compares its compiled-in version against the server's advertised version. If they differ, it downloads the latest binary from the server's /api/v1/agent/download endpoint, verifies the SHA256 checksum, atomically replaces its own binary, and exec-restarts. On systemd, this is seamless — the service continues running with the new binary. If the versions already match, the update is skipped to prevent exec-loops.

Related

• approved -- manage enrollment patterns
• runs -- view run history for envoys
• inventory -- query envoys by traits
• task -- dispatch ad-hoc commands to envoys