vigocli task
Dispatch and monitor ad-hoc commands or named tasks on envoys.
Subcommands
| Subcommand | Description |
|---|---|
run |
Run a command or named task on targeted envoys |
status |
Show status and results for a task run |
list |
List recent task runs |
Usage
vigocli task [subcommand] [flags]
run
Run an ad-hoc command or a named task on targeted envoys. The CLI polls until the task completes, then displays results.
vigocli task run <command-or-task-name> [flags]
Flags
| Flag | Short | Default | Description |
|---|---|---|---|
--target |
Target spec: hostname, glob (*.web.*), UUID, or trait filter (os.distro=ubuntu) |
||
--timeout |
60 |
Command timeout in seconds | |
--operator |
current user | Operator name for audit | |
--batch-size |
Batch size: count (5) or percentage (25%) |
||
--max-failures |
Max failures before abort: count (2) or percentage (10%) |
||
--health-check-url |
URL to probe between batches (abort on non-2xx) | ||
--nice |
0 |
CPU/IO priority 0–19 (0 = normal, 19 = lowest) | |
--dry-run |
false |
Display batch plan without executing | |
--force |
false |
Bypass the server-side guardrail check (agent guardrails still apply) | |
--param |
Task parameter (key=value), repeatable |
Guardrails
The server refuses to dispatch a command whose text matches the
hardcoded dangerous-pattern list — systemctl stop vigo, pkill vigo,
an rm / unlink targeting /srv/vigo/, etc. Without --force the
CLI prints the reason and prompts:
warning: server-side guardrail blocked this command
reason: command matches dangerous pattern
pattern: systemctl stop vigo
note: the agent's hardcoded guardrails still apply on each envoy.
Proceed anyway? [y/N]
--force skips the prompt and bypasses the server-side check in one
step. Bypassed dispatches land on the audit hash chain as task.dispatch
with {"forced":true} in the payload; refused dispatches (operator
declined, no --force) land as task.blocked with the matched pattern.
--force does not bypass the agent's guardrails on each envoy —
that list (agent/src/guardrails.rs) is the final safety boundary and
is hardcoded. A --force'd command that the agent still refuses will
come back as rejected per target.
Examples
Run an ad-hoc command
vigocli task run "uptime" --target "*.web.*"
Task t1a2b3c4 dispatched
--- web-01.example.com [complete] exit=0 42ms
12:30:01 up 45 days, 3:22, 0 users, load average: 0.15, 0.10, 0.05
--- web-02.example.com [complete] exit=0 38ms
12:30:01 up 30 days, 1:15, 0 users, load average: 0.22, 0.18, 0.12
Run a named task with parameters
vigocli task run restart-app --target "*.web.*" --param env=staging
Rolling execution with batch control
vigocli task run "systemctl restart nginx" --target "*.web.*" \
--batch-size 25% --max-failures 2 \
--health-check-url "http://lb.example.com/health"
Dry-run to preview batch plan
vigocli task run "uptime" --target "*.web.*" --batch-size 2 --dry-run
Dry-run batch plan:
Batch 0: web-01.example.com, web-02.example.com
Batch 1: web-03.example.com, web-04.example.com
2 batch(es), 4 target(s), 0 offline
status
Show status and results for an existing task run.
vigocli task status <id>
Example
vigocli task status t1a2b3c4
Task: t1a2b3c4
Command: uptime
Target: *.web.*
Operator: admin
Status: complete
Targets: 2
Created: 2026-03-13 12:30
Started: 2026-03-13 12:30
Finished: 2026-03-13 12:30
--- web-01.example.com [complete] exit=0 42ms
12:30:01 up 45 days, 3:22, 0 users, load average: 0.15, 0.10, 0.05
list
List recent task runs.
vigocli task list [flags]
Flags
| Flag | Short | Default | Description |
|---|---|---|---|
--limit |
20 |
Maximum number of tasks to display |
Example
vigocli task list --limit 5
ID COMMAND TARGET STATUS TARGETS CREATED
t1a2b3c4 uptime *.web.* complete 4 2026-03-13 12:30
t5e6f7g8 systemctl resta... *.web.* complete 4 2026-03-13 11:00
Related
- workflow -- multi-step workflow orchestration
- query -- query trait values from envoys
- runs -- view convergence run history