Skip to main content

Operating Writ from the terminal with eactl

Objective​

Run a short, realistic eactl sequence a platform engineer uses to take a governed policy from a local check to a deployed bundle, and inspect the run afterward. Use only real eactl commands, and know which ones this lab actually exercises.

Concept​

eactl is the EnforceAuth Writ CLI, a Go binary that embeds OPA Control Plane and adds EnforceAuth commands on top. From lesson 2 you already met deploy-action, the GitHub Action that ships bundles from CI with OIDC. eactl is the counterpart you drive from a terminal for the same control-plane work: pre-flight a deploy, run the policy pipeline, and check run history.

Install is standard Go tooling, so the binary lands in ~/go/bin:

go install github.com/EnforceAuth/mono/packages/ctl/cmd/eactl@latest
eactl version

eactl version prints both the eactl version and the underlying OPA Control Plane version, which is the first thing to confirm when you are unsure what a box is running.

A worked sequence​

A platform engineer standing up a policy for one entity runs roughly this. The IDs below are entity and tenant UUIDs from your EnforceAuth tenant.

# 1. Confirm the CLI and the embedded control-plane version.
eactl version

# 2. Pre-flight the deploy target before running anything.
#    Validates config, secret access, bundle-destination access, and Git reachability.
eactl diagnose preflight \
  --entity-id dd59ad6c-9510-4d3d-9346-ccc098469243 \
  --lambda policy-pipeline-dev

# 3. Run the policy pipeline for the entity.
#    This fetches effective config, runs policy tests, builds the bundle, and deploys it.
export EA_API_ENDPOINT="https://api.enforceauth.example"
export EA_API_TOKEN="…"   # or pass --api-token
eactl pipeline \
  --tenant-id a3d84813-5598-4c83-b1e4-717d2e722cdf \
  --entity-id dd59ad6c-9510-4d3d-9346-ccc098469243

# 4. Inspect run history for the tenant, then drill into one run.
eactl diagnose runs list --tenant-id a3d84813-5598-4c83-b1e4-717d2e722cdf
eactl diagnose runs show <run-id>

Read the flow top to bottom. Step 2 is a dry check: diagnose preflight verifies the deploy can succeed (config, secret read, S3 bundle destination, Git connectivity) before any bundle is built. Step 3 is the real work: eactl pipeline runs test, build, and deploy for the entity, which is the same test-then-sign discipline lesson 2 described, driven from your terminal instead of CI. Steps 4 uses diagnose to answer "what ran, and did it succeed?" from recorded run history.

Two grounding notes so you do not over-claim what the CLI does:

  • The pipeline resolves its endpoint and token from --api-endpoint / --api-token or the EA_API_ENDPOINT / EA_API_TOKEN environment variables, and it fails closed if neither is set. --tenant-id and --entity-id are required.
  • eactl also exposes the embedded OPA Control Plane commands directly: eactl build builds a bundle, eactl run runs the control-plane server, and eactl migrate handles the control-plane database. This lesson uses eactl pipeline and eactl diagnose because those are the day-to-day operator verbs. If you are unsure of a subcommand's flags, run eactl <command> --help rather than guessing.

Hands-on lab​

This course's graded artifact is still the OPA policy in ../lab/, not a live eactl run, since the pipeline needs a real EnforceAuth tenant and API token. What you can and should do locally is the check that step 3 runs first: prove the policy is green before it would ever be built into a bundle.

git clone https://github.com/EnforceAuth/university-labs.git
cd university-labs
opa test courses/getting-started-writ-control-plane -v

When that reports PASS: 8/8, you are looking at exactly the gate eactl pipeline enforces internally before it builds and deploys. The CLI would run this same policy test, and only a passing result proceeds to build and deploy. Treat a local opa test pass as the precondition for every command in the worked sequence above.

Check for understanding​

  1. In the worked sequence, what does eactl diagnose preflight check, and why run it before eactl pipeline?
  2. Which three actions does eactl pipeline perform for an entity, and how does it get its API endpoint and token?
  3. eactl embeds OPA Control Plane. Name one embedded command it exposes directly and say what it does, without inventing flags.