CLI: LOAD mode¶
LOAD projects contain only .eve-iac.yml. Use them when a pipeline or script must operate an existing EVE lab without owning topology in Git.
Create the project (local only)¶
eve-iac load writes the marker. It does not call eve-iac-agent and does not need EVE_IAC_URL.
eve-iac load /Customers/OSPF.unl
eve-iac load /Customers/OSPF.unl ./IaC/ospf-watch
eve-iac load /Customers/OSPF.unl --name ospf-watch
eve-iac load /Customers/OSPF.unl ./IaC/ospf --force
JSON output (--json):
{"project": "/path/to/IaC/OSPF", "source_lab": "/Customers/OSPF.unl", "mode": "load"}
Idempotent: running load again on the same directory with the same source.lab succeeds without changing the marker. Use --force to replace an existing marker.
Allowed agent operations¶
After EVE_IAC_URL, TLS pin, and token are set:
| Command | LOAD |
|---|---|
status |
yes |
inspect |
yes (--refresh optional) |
exec start\|stop\|wipe |
yes (wipe needs --yes) |
link quality\|suspend\|resume |
yes. link quality --save persists the UNL (admin, unlocked lab). Omitted --save and suspend stay runtime-only. Neither writes YAML |
validate |
no (CLI rejects before agent) |
import |
no |
plan / reconcile |
no |
deploy / destroy |
no |
export-config |
no (replaces an EVE startup-config blob; managed lab only) |
Example session:
export EVE_IAC_URL=https://eve.example:8787
export EVE_IAC_CA_FILE=./eve-iac-ca.pem
eve-iac --json login --username admin --password "$EVE_IAC_PASSWORD"
export EVE_IAC_TOKEN
eve-iac load /Customers/OSPF.unl ./IaC/ospf
eve-iac inspect ./IaC/ospf --json
eve-iac exec ./IaC/ospf start
eve-iac exec ./IaC/ospf wipe --yes
eve-iac link quality ./IaC/ospf --from n_1:e0/0 --to n_2:e0/1 --delay 50
eve-iac link quality ./IaC/ospf --from n_1:e0/0 --to n_2:e0/1 --delay 50 --save
Rejected locally:
eve-iac plan ./IaC/ospf
# plan is not allowed in mode load (allowed: status, inspect, exec start|stop|wipe, link quality|suspend|resume)
Exit code 2 (usage), code operation_not_allowed.
Payload shape¶
pack_lab on a LOAD directory sends only lab (from source.lab) and manifest to the agent — no yaml or files. Python:
from eveiac import init_load, pack_lab
root = init_load("/Customers/OSPF.unl", "./IaC/ospf")
packed = pack_lab(root)
# packed.payload == {"lab": "/Customers/OSPF.unl", "manifest": "..."}
vs import in CI¶
eve-iac import ./lab |
eve-iac load /path.unl |
|
|---|---|---|
| Prerequisite | IMPORT marker + Git files from VSIX or hand-written | EVE lab path only |
| Agent on init | yes (import_project) |
no |
| Topology in Git | yes | no |
| Later edits | plan/reconcile | lifecycle + live link quality/suspend |
For Git-driven desired state, use CREATE or IMPORT. For runbooks that start/stop/wipe or apply live NETEM/suspend on existing labs, use LOAD.
See also: Recipes, project structure.