wxctl is a deterministic engine with no LLM of its own: your agent writes the config.yaml, and wxctl validates, plans, and executes it. This guide is the runbook for driving the full loop from an agent with only the binary. The same runbook ships in the repository as AGENTS.md.

​
The canonical loop

Run these in order; each step is safe to repeat.
1

Discover

wxctl resources lists every kind (no credentials). wxctl explain <kind> shows fields, dependencies, and endpoints; wxctl explain with no kind prints the config model plus the full kind list.
2

Author

Write config.yaml: separate resources with ---, give each a top-level kind and ref_name, and wire them with ${kind.ref_name} references. Keep secrets out of YAML with ${env:VAR}.
3

Validate and plan

wxctl validate -f config.yaml runs schema and reference checks offline. wxctl plan -f config.yaml previews the create/update/delete plan. Non-blocking advisories, when any apply, appear in the JSON warnings[] array and a ▌ Advisories section; they never change valid or the exit code.
4

Apply, test, destroy

wxctl apply converges to the desired state, wxctl test runs the config’s own kind: test suite against the live deployment, and wxctl destroy tears it down.

​
Credential-free discovery

wxctl resources, wxctl explain, and wxctl validate need no profile and make no network calls. Learn the catalog and the config model before you author anything.

​
Machine-readable output

Add --output json to validate, plan, apply, test, or destroy (and -o json to resources or explain) to emit exactly one JSON document on stdout; logs stay on stderr.
CommandJSON top-level keys
plansummary, operations[]
apply, destroyrun_id, summary, succeeded[], failed[], skipped[]
testrun_id, passed, failed, tests[]
validatevalid, errors[], warnings[], fix_prompt
On failure the JSON is still written to stdout (with failed[] or errors[] populated) before a nonzero exit, so you always get structured detail. The wxctl mcp serve MCP server exposes the same operations as tools with identical JSON shapes.

​
Exit codes

See the Commands reference for the full table. In short: 0 success, 1 error, 2 usage error. plan returns 0 for any valid plan, including one with pending changes.

​
Profiles

Endpoints and auth live in a profile at ~/.wxctl/profiles.yaml. Create one with wxctl init, select it with -p <name> or WXCTL_PROFILE, and see Profiles and credentials for details.

​
Error recovery

Fix a bad config

Run wxctl validate --fix-prompt, or read fix_prompt from the --output json document, for a ready-to-apply correction.

Diagnose a failed run

wxctl debug prints an agent-ready diagnosis of the latest failed run (-o json for a bundle).