README
¶
terraform-axi
An axi CLI for the public Terraform Registry, written in Go.
It replaces the public-registry tools of the HashiCorp terraform MCP server with agent-ergonomic commands: token-efficient TOON output, pre-computed aggregates, and no opaque ids for the model to carry.
Example: reading the aws_s3_bucket docs through the MCP takes two chained tool calls with a numeric id in between.
Here it is one command:
terraform-axi provider hashicorp/aws resource s3_bucket
Install
With the Go toolchain:
go install github.com/aziz-shoko/terraform-axi@latest
Or from a checkout (requires Task):
git clone https://github.com/aziz-shoko/terraform-axi.git
cd terraform-axi
task build
then put ./terraform-axi on PATH, e.g. ln -s "$PWD/terraform-axi" /usr/local/bin/terraform-axi.
Both paths produce a binary that self-reports its version: task build injects it via ldflags, go install builds fall back to the Go module metadata.
Then install the agent integration - the SessionStart hooks (Claude Code, Codex, OpenCode) and the Claude Code skill:
terraform-axi setup
To verify, run a bare terraform-axi: it prints the home view that new agent sessions now receive ambiently at SessionStart.
Commands
Running terraform-axi with no arguments shows the live command surface.
The provider, module, and policy families are implemented.
| Command | What it does |
|---|---|
provider <ns>/<name> [version] |
Overview: tier, downloads, versions, per-category doc counts. |
provider <ns>/<name> <category> [--query <str>] |
List docs in a category (resources, data-sources, functions, guides, actions, list-resources; singular aliases accepted). |
provider <ns>/<name> <category> <slug> |
Full markdown for one doc, truncated past 16 KB unless --full. |
module search <query>... [--offset <n>] |
Search modules: id, downloads, verified, description. Bare module <query> is an alias. |
module <ns>/<name>/<provider>[/<version>] |
Details: provider constraints, required inputs, output names, counts. --full tables every input and output. |
policy search <query>... |
Search Sentinel policy libraries: id, title, downloads. Bare policy <query> is an alias. |
policy <ns>/<name> |
Library details: .sentinel policy list, readme (truncated past 16 KB unless --full), source tree link. |
setup [hooks|skill] |
Install agent integration: SessionStart hooks (Claude Code, Codex, OpenCode) and the Claude Code skill. Bare setup installs both. |
<command> --help |
Usage, flags, and examples. |
--version |
Build version, commit, and date. |
Agent skill
skills/terraform-axi/SKILL.md documents the CLI for agent harnesses (when to use it, workflow, tips).
It is embedded in the binary: terraform-axi setup installs it to ~/.claude/skills/terraform-axi/SKILL.md along with the SessionStart ambient-context hooks, no repo checkout needed.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success, including empty result sets (a query matching nothing is an answer, not an error). |
| 1 | Error: named entity not found, registry/network failure. Structured error: section on stdout. |
| 2 | Usage error: unknown command, unknown flag, malformed arguments. |
Development
task test # unit tests (race detector, fixture-backed)
task lint # golangci-lint
task golden # regenerate golden files after intentional output changes
task smoke # live tests against registry.terraform.io (TF_AXI_LIVE=1)
Unit tests run against recorded registry JSON served via httptest; nothing in task test touches the network.
Live smoke tests are always compiled but skip unless TF_AXI_LIVE=1, and run weekly in CI.
Design docs live in docs/, starting with docs/terraform-axi-design.md.
License
Apache-2.0. See LICENSE.
Documentation
¶
Overview ¶
Command terraform-axi is an agent-ergonomic CLI over the public Terraform Registry. The main package lives at the module root so `go run github.com/aziz-shoko/terraform-axi@latest <command>` stays short.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
cli
Package cli is the dispatcher: it routes arguments to command families and owns the exit-code mapping.
|
Package cli is the dispatcher: it routes arguments to command families and owns the exit-code mapping. |
|
command/module
Package module implements the `module` command family: registry search and module details with tabular TOON inputs/outputs - the biggest raw token win over the MCP's JSON.
|
Package module implements the `module` command family: registry search and module details with tabular TOON inputs/outputs - the biggest raw token win over the MCP's JSON. |
|
command/policy
Package policy implements the `policy` command family: the registry's thin Sentinel policy-library surface, kept deliberately minimal.
|
Package policy implements the `policy` command family: the registry's thin Sentinel policy-library surface, kept deliberately minimal. |
|
command/provider
Package provider implements the `provider` command family: the flagship collapse of the MCP's two-call, id-chained provider-doc flow into single legible commands.
|
Package provider implements the `provider` command family: the flagship collapse of the MCP's two-call, id-chained provider-doc flow into single legible commands. |
|
command/setup
Package setup implements the `setup` command family: agent-integration plumbing (axi principle 7, ambient context).
|
Package setup implements the `setup` command family: agent-integration plumbing (axi principle 7, ambient context). |
|
output
Package output owns the rendering contract for everything terraform-axi prints: TOON for structured data, delimited raw blocks for large markdown bodies, and structured errors.
|
Package output owns the rendering contract for everything terraform-axi prints: TOON for structured data, delimited raw blocks for large markdown bodies, and structured errors. |
|
registry
Package registry is the HTTP client for the public Terraform Registry (https://registry.terraform.io).
|
Package registry is the HTTP client for the public Terraform Registry (https://registry.terraform.io). |
|
registry/registrytest
Package registrytest serves recorded registry JSON fixtures over httptest for unit tests.
|
Package registrytest serves recorded registry JSON fixtures over httptest for unit tests. |
|
testutil
Package testutil holds shared test helpers.
|
Package testutil holds shared test helpers. |
|
version
Package version holds build metadata injected at link time via -ldflags "-X github.com/aziz-shoko/terraform-axi/internal/version.Version=...".
|
Package version holds build metadata injected at link time via -ldflags "-X github.com/aziz-shoko/terraform-axi/internal/version.Version=...". |