{
  "markdown": "# vegastack — `@vegastack/cli`\n\nA deterministic, offline knowledge harness for coding agents. One npm install gives **Claude Code, Codex, Cursor, and Gemini** local, citable competence over **31 Terraform providers** — without web search, MCPs, or model-knowledge gaps.\n\n```bash\nnpm i -g @vegastack/cli         # ~5 MB CLI + ~12 MB compressed bundle (97 MB on disk after extract)\nvegastack doctor                     # verify environment\nvegastack skills install --agent all # register skills with all installed agents\n```\n\n[![npm](https://img.shields.io/npm/v/@vegastack/cli.svg)](https://www.npmjs.com/package/@vegastack/cli)\n[![CI](https://github.com/vegastack/vegastack-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/vegastack/vegastack-cli/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n---\n\n## What's inside\n\n- **31 Terraform providers' upstream docs** mirrored daily from their GitHub repos — `aws`, `azure`, `gcp`, `cloudflare`, `kubernetes`, `helm`, `vault`, `digitalocean`, `github`, `gitlab`, `vercel`, `netlify`, `datadog`, `grafana`, `splunk`, `pagerduty`, `okta`, `auth0`, `crowdstrike`, `1password`, `mongodb-atlas`, `snowflake`, `redis-cloud`, `clickhouse`, `pinecone`, `ansible`, `random`, `tls`, `time`, `local`, `external`.\n- **Per-provider `MANIFEST.json`** — resource schemas, argument lists, enum values, import syntax, deprecation flags, HCL reference graph, recommended companions.\n- **`vegastack tf <query>`** — a deterministic discovery CLI. Returns one JSON envelope with `files[]`, `knowledge[]` (curated recent-change facts), `recipes[]` (multi-provider scaffolds), `concept_aliases_used[]` (natural-language → resource mapping). Top-K results arrive with full schemas inline.\n- **Spec-compliant skill** for the [Anthropic Agent Skills Standard](https://agentskills.io/specification), packaged as a Claude Code plugin and installable into Codex (`.agents/skills/`), Cursor (`.cursor/rules/`), and Gemini (`gemini-extension.json`).\n\n## How this differs from `hashicorp/agent-skills`\n\nHashiCorp shipped a competing agent-skills bundle in February 2026. They're complementary, not competitive:\n\n| Aspect       | `hashicorp/agent-skills`                                                                                | `@vegastack/cli`                                                                                                |\n| ------------ | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |\n| Audience     | Provider authors                                                                                        | Provider consumers (devops/SRE/platform/sec engineers)                                                          |\n| What it ships | \"How to write a Terraform provider\", \"Run acceptance tests\", azure-verified-modules patterns           | Per-resource manifest, import-id syntax, deprecation flags, recipes, knowledge cards for 31 providers           |\n| Installs to  | Claude Code skills                                                                                      | Claude Code / Codex / Cursor / Gemini / Continue / Aider via npm                                                |\n| License      | MPL-2.0                                                                                                 | MIT                                                                                                             |\n\nBoth can be installed side-by-side. Use `hashicorp/agent-skills` when authoring or testing your own provider; use `@vegastack/cli` when writing or modifying Terraform configurations that consume providers.\n\n## Install\n\n> **v0.1 status:** internal-only release via **GitHub Packages**. The public-npm + skill-registry install paths below are reserved for the v1.0 public ship; they will not resolve a package today. Use the \"Install (internal — GitHub Packages)\" section first.\n\n### Install (internal — GitHub Packages)\n\n`@vegastack/cli` is published to GitHub Packages under the `VegaStack` org. Three steps:\n\n**1. Create a GitHub PAT with `read:packages` scope**\n\nGo to <https://github.com/settings/tokens?type=beta> → Generate new token → resource access: `VegaStack` org → permissions: **Packages → Read-only**. Save the token (`ghp_...`).\n\n**2. Authenticate npm to the GitHub Packages registry**\n\nAdd to `~/.npmrc` (create if missing):\n\n```ini\n@vegastack:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=ghp_YOUR_PAT_HERE\n```\n\n**3. Install the CLI**\n\n```bash\n# Global (recommended for CLI tools):\nnpm i -g @vegastack/cli\n\n# Or local to a project:\nnpm i @vegastack/cli\n```\n\nThe npm postinstall downloads the docs bundle (~12 MB) from `https://bundles.vegastack.com/cli/...` (Cloudflare R2). It's content-addressed and SHA-verified; on R2 outage it falls back to GitHub Releases of the bundle repo. After install:\n\n```bash\nvegastack doctor   # should report bundle found\nvegastack tf \"S3 bucket with versioning enabled\"\n```\n\nTo point at a local bundle tree instead (development against an unpublished build), set `VEGASTACK_BUNDLE_DIR` to the absolute path of the bundle's `terraform-providers/` directory before running any vegastack command.\n\nTo skip the postinstall network fetch entirely (silent), prefix install with:\n\n```bash\nVEGASTACK_SKIP_POSTINSTALL=1 npm i -g @vegastack/cli\n```\n\n### Install (public — coming with v1.0)\n\n```bash\n# These paths will resolve once v1.0 ships publicly. Not active in v0.1.\nnpm i -g @vegastack/cli                # public npm registry\nnpx skills add @vegastack/cli          # Skills.sh\ntessl install @vegastack/cli           # Tessl\n/plugin install vegastack-cli          # Claude Code plugin marketplace\n```\n\n```bash\nvegastack doctor\n# ✓ Node.js: v20.10.0\n# ✓ Docs bundle: v2026.04.28 at /Users/.../.config/vegastack/bundle (31 providers, schema_version=1, generated ...)\n# ✓ jq (optional): jq-1.7.1\n# ✓ ripgrep (optional): ripgrep 14.1.0\n```\n\n> **Native TypeScript runtime**: `vegastack tf` is fully native — no Python, no shell-outs to a foreign runtime. Top-K results arrive with the full manifest schema (`required_args`, `optional_args`, `import_syntax`, `deprecated`, …) and the inline `## Example Usage` block, so a typical agent task collapses from ~15 tool calls to 1–2. Add `--debug` to see per-stage timings.\n\n## Register the skill with your coding agent(s)\n\n```bash\n# Install for ALL detected agents at once:\nvegastack skills install --agent all\n\n# Or pick:\nvegastack skills install --agent claude-code               # global (~/.claude/plugins/)\nvegastack skills install --agent codex                     # global (~/.agents/skills/)\nvegastack skills install --agent cursor --scope project    # writes .cursor/rules/vegastack-cli.mdc\nvegastack skills install --agent gemini --scope project    # writes gemini-extension.json + CONTEXT.md\n\n# What's currently registered?\nvegastack skills status --agent all\n\n# Cleanup:\nvegastack skills uninstall --agent cursor --scope project\n```\n\n`--scope global` writes to your home dir; `--scope project` writes to the current working directory. Cursor and Gemini are project-scoped only (their config files live next to your code). Add `--dry-run` to preview without writing.\n\n| Agent           | Scope            | Files written by `vegastack skills install`                                                              |\n| --------------- | ---------------- | --------------------------------------------------------------------------------------------------- |\n| **Claude Code** | global           | `~/.claude/plugins/vegastack-cli/` (symlink to package; auto-updates with the CLI)        |\n| **Codex**       | global / project | `~/.agents/skills/vegastack/` (or `<cwd>/.agents/skills/...`); optionally `~/.codex/AGENTS.md` |\n| **Cursor**      | project only     | `<cwd>/.cursor/rules/vegastack-cli.mdc`                                                   |\n| **Gemini**      | project only     | `<cwd>/gemini-extension.json` + `<cwd>/CONTEXT.md`                                                  |\n\n## Use it\n\nOnce installed, your agent auto-detects the skill on Terraform-related prompts. You can also invoke `vegastack` directly:\n\n```bash\nvegastack tf \"create an S3 bucket with versioning enabled\"\n# → JSON envelope; files[].manifest_entry has the full schema; .example_usage has the canonical HCL block.\n\nvegastack tf \"import an existing Cloudflare DNS record\"\n# → cloudflare_dns_record (NOT the deprecated v4 cloudflare_record); import_syntax inline.\n\nvegastack tf \"zero-trust internal app cloudflare access aws alb okta\" --max 20\n# → recipes[] surfaces the multi-provider scaffold; files[] from each provider.\n\nvegastack refresh    # pull a newer bundle (when upstream docs change)\n```\n\nThe agent reads the response and writes citable HCL. The docs are always local, always fresh, always deterministic — no network calls at query time.\n\n## How is this better than asking an LLM directly?\n\n| Failure mode                                                 | LLM alone   | With vegastack                                               |\n| ------------------------------------------------------------ | ----------- | ------------------------------------------------------- |\n| Invented resource name (`aws_lb_v2`)                         | common      | impossible — null lookups raise an explicit error       |\n| Stale rename (`cloudflare_record` → `cloudflare_dns_record`) | silent fail | knowledge card surfaces the rename                      |\n| Fabricated import-ID format                                  | common      | `import_syntax` returns the exact composite-ID format   |\n| Missed soft-dependency (EC2 needs VPC + subnet + SG)         | common      | `recommended_companions` widens the response            |\n| \"Protect from bots\" → wrong Cloudflare resource              | common      | concept aliases map natural language to right resources |\n| Multi-provider scaffold (zero-trust, scalable backend)       | error-prone | recipes ship working composable HCL fragments           |\n\niter-1 benchmark on 4 representative tasks (S3 versioning, Cloudflare DNS import, k8s deployment, ECS+RDS+Datadog stack):\n\n| Configuration                            | Pass rate        | Time     | Tokens  |\n| ---------------------------------------- | ---------------- | -------- | ------- |\n| **with-skill**                           | **100% (39/39)** | 110s avg | 43k avg |\n| baseline (no docs, training memory only) | 74% (31/39)      | 59s avg  | 20k avg |\n\nThe ~2× cost above was measured against v0.1's Python harness; v0.2 collapses it via enrichment (single-call responses with full schemas + example usage inline). See [PORT-ROADMAP.md](PORT-ROADMAP.md) for the design details.\n\n## Layout\n\n```\n@vegastack/cli/\n├── .claude-plugin/plugin.json     # Claude Code plugin manifest\n├── .agents/skills/vegastack/ # Codex skill location (symlink to ./skills/vegastack/)\n├── AGENTS.md                      # Codex / generic-agent project instructions\n├── CLAUDE.md                      # Defers to AGENTS.md\n├── cursor-rule.mdc                # Drop-in Cursor rule template\n├── gemini-extension.json          # Gemini Code Assist extension\n├── CONTEXT.md                     # Gemini agent context\n├── skills/vegastack/\n│   ├── SKILL.md                   # The Anthropic Agent Skills standard skill\n│   └── references/                # 5 reference files (CLI, manifest, knowledge, recipes, aliases)\n├── npm/\n│   ├── install.js                 # postinstall: downloads bundle from GH Releases\n│   └── run.js                     # npm bin entry, delegates to dist/cli.js\n├── src/                           # TypeScript source\n│   ├── cli.ts                     # commander.js entry\n│   ├── commands/                  # doctor, install, refresh, skills, tf\n│   ├── agents/                    # claude-code, codex, cursor, gemini\n│   └── lib/                       # paths, log, bundle, discover\n├── dist/                          # compiled JS (published, not committed)\n├── docs/                          # docs site sources\n├── tests/                         # vitest specs\n└── PORT-ROADMAP.md                # historical: v0.2 native-TS port plan (now shipped)\n```\n\n## Development\n\n```bash\ngit clone https://github.com/vegastack/vegastack-cli.git\ncd vegastack-cli\nnpm install                    # postinstall fails harmlessly if no bundle yet\nnpm run build                  # tsc → dist/\n\n# Run against the upstream repo's bundle for local testing:\nVEGASTACK_BUNDLE_DIR=/Users/you/projects/engg-vegastack-agent-tf-providers/terraform-providers \\\n  node dist/cli.js doctor\n\n# Build a local bundle and use it via file://:\n( cd /Users/you/projects/engg-vegastack-agent-tf-providers && \\\n  bash scripts/build_bundle.sh --version $(date +%Y.%m.%d) )\nVEGASTACK_BUNDLE_URL=file:///path/to/dist/vegastack-bundle-vYYYY.MM.DD.tar.gz \\\nVEGASTACK_BUNDLE_DIR=/tmp/test-bundle \\\n  node npm/install.js\n```\n\n## Releasing (internal maintainers)\n\nThis repo ships an `/ship` Claude Code skill at `.claude/skills/ship/SKILL.md` that handles the full release cycle. It's project-local — it only triggers inside this repo, never on other projects.\n\n**When to invoke:** every time you cut a v0.1.x release. Trigger phrases include `/ship`, \"cut a release\", \"ship the cli\", \"publish a new version\", \"tag v0.1.x\", \"let's release this\".\n\n**What it does, in order:**\n\n1. **Pre-flight** — runs build + typecheck + tests + lint across all 3 codebases (CLI 398 tests, `apps/mcp` 19, `apps/dashboard` 9). Aborts if anything fails.\n2. **Diff analysis** — `git diff` + `git status` + `git log` + reads the latest version actually published to GitHub Packages (`gh api …/orgs/VegaStack/packages/npm/cli/versions`) so the version chronology check uses the source of truth, not local `package.json` state which can drift.\n3. **Doc audit** — exhaustive grep across every `.md` file (excluding `docs/{planning,status,contracts,evals}/**` which are frozen historical / spec records) for stale references to anything that changed in the diff. Updates inline.\n4. **Drafts version + changelog + commit message + GH release notes** — defaults to patch unless the diff scope calls for minor. Never suggests major. Validates the proposed version against the latest GitHub Packages version. Presents everything; waits for your confirmation.\n5. **Bumps version** in `package.json`, `apps/mcp/package.json`, and `apps/dashboard/package.json` (kept in sync). Prepends the changelog entry.\n6. **Waits for explicit `push` confirmation.** Will not commit, push, tag, or release until you say so.\n7. **Executes ship** — stages files by name (never `-A`), commits with conventional-commit message + `Co-Authored-By` trailer, `git pull --rebase`, `git push`, `git tag v<version>`, `git push --tags`. The tag push is the trigger for `.github/workflows/publish-internal.yml` which publishes the npm package to GitHub Packages.\n8. **Post-ship verification** — `gh run watch` until the workflow exits 0, confirms the version landed in GH Packages, prints an install snippet for testers.\n\n**Safety gates baked in:**\n\n- Never bypasses the `prepublishOnly` bundle-pin guard locally (only CI does, via `VEGASTACK_ALLOW_PENDING_BUNDLE_SHA=1`).\n- Never invokes `gh workflow run publish-internal.yml` — the tag push is the only correct trigger.\n- Never modifies `release.yml` (the dormant public-npm path).\n- Never touches the bundle repo (`engg-vegastack-agent-tf-providers`) — it has its own release cron.\n- Never deploys `apps/mcp` or `apps/dashboard` — Cloudflare Workers Builds owns those, redeploying automatically on push to main.\n- Never `git add -A`, never force-push.\n\n**Prerequisites:** `gh` CLI authenticated to GitHub (`gh auth status`), git remote configured for the repo, GitHub Actions secrets in place (`R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME=vegastack-agent-kb`).\n\n## How it's distributed\n\nThis repo publishes the **CLI** to npm as `@vegastack/cli`. The **docs bundle** is built daily by the upstream `vegastack/engg-vegastack-agent-tf-providers` pipeline and uploaded to this repo's GitHub Releases as a tarball. The CLI's postinstall downloads the latest release matching the installed CLI version (or via `VEGASTACK_BUNDLE_URL`).\n\n| Repo                                          | Role                          | Cadence                            |\n| --------------------------------------------- | ----------------------------- | ---------------------------------- |\n| `vegastack/vegastack-cli` (this)              | CLI source, npm publish       | semver, on PR merge via Changesets |\n| `vegastack/engg-vegastack-agent-tf-providers` | Daily docs sync, bundle build | nightly cron 02:00 UTC             |\n\n## Environment variables\n\n| Variable                     | Default                                                 | Purpose                                                                                              |\n| ---------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |\n| `VEGASTACK_BUNDLE_DIR`            | `~/.config/vegastack/bundle`                            | Where the docs bundle lives after install. Override to test alternate bundles.                       |\n| `VEGASTACK_BUNDLE_URL`            | `https://github.com/.../vegastack-bundle-vX.Y.Z.tar.gz` | Override the download URL. Use `file:///path/to/bundle.tar.gz` for offline / air-gapped installs.    |\n| `VEGASTACK_SKIP_POSTINSTALL`      | (unset)                                                 | Set to `1` to skip the postinstall download (useful in CI when you provision the bundle separately). |\n| `VEGASTACK_BUNDLE_TIMEOUT_MS`     | `60000`                                                 | Per-attempt fetch timeout.                                                                           |\n| `VEGASTACK_BUNDLE_RETRIES`        | `2`                                                     | Number of retries on transient failures (3 attempts total).                                          |\n| `HTTPS_PROXY` / `HTTP_PROXY` | (unset)                                                 | Standard proxy URLs; `vegastack install` routes the bundle download through `undici`'s ProxyAgent.        |\n| `NO_PROXY`                   | (unset)                                                 | Comma-separated host substrings to bypass the proxy. `*` disables proxying entirely.                 |\n| `NO_COLOR`                   | (unset)                                                 | Set to disable colored output.                                                                       |\n\n## Troubleshooting\n\n### Postinstall failed but `vegastack doctor` says \"bundle missing\"\n\nRun `vegastack install` (or `vegastack refresh` to force a fresh download). If it still fails, the troubleshooting tree:\n\n```\nnetwork unreachable          → check `curl -fI <bundle URL>` from the same shell\nHTTP 403 / rate limit         → wait a minute and retry; GitHub anonymous limits are generous\nbehind a corporate proxy      → set HTTPS_PROXY (and NO_PROXY); see \"Proxied / air-gapped\" below\nSHA256 mismatch on every try  → file a security report — see SECURITY.md\n\"tar binary not found\"        → on Windows < 1809: install bsdtar or git-bash; on Alpine: `apk add tar`\n```\n\n`vegastack doctor --json` produces machine-readable output that's the cleanest thing to attach to a bug report.\n\n### Proxied / air-gapped installs\n\nThe CLI honors `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` automatically (via Node's bundled `undici`). If the proxy can't reach GitHub Releases, fall back to a local file:\n\n```bash\n# 1. Mirror the bundle by hand:\ncurl -L -O https://github.com/vegastack/vegastack-cli/releases/download/v0.1.0/vegastack-bundle-v0.1.0.tar.gz\ncurl -L -O https://github.com/vegastack/vegastack-cli/releases/download/v0.1.0/vegastack-bundle-v0.1.0.tar.gz.sha256\n\n# 2. Point the installer at the local copy:\nVEGASTACK_BUNDLE_URL=file:///abs/path/to/vegastack-bundle-v0.1.0.tar.gz \\\n  npm i -g @vegastack/cli\n```\n\nFor corporate distribution, host the tarball + sidecar `.sha256` on an internal server (HTTPS only) and set `VEGASTACK_BUNDLE_URL` org-wide. The SHA256 verification still applies.\n\n### Sudo / global-install path question\n\n`npm i -g @vegastack/cli` (with or without `sudo`) downloads the bundle to **the invoking user's** `~/.config/vegastack/bundle/` — not `/root/`. The CLI binary lives in npm's global prefix (`/usr/local/lib/node_modules/...` typically), but bundle data follows `$HOME` of whoever runs `vegastack`. If multiple users on the machine each want their own bundle, that's already how it works.\n\n### Windows symlinks fail with `EPERM`\n\n`vegastack skills install --agent claude-code` tries to symlink the package into `~/.claude/plugins/`. Symlinks on Windows require either:\n\n- **Developer Mode** enabled (Settings → For Developers, Win10 1703+), or\n- Running the shell as Administrator.\n\nIf neither applies, the installer **falls back to a recursive copy** automatically — same end state, but you'll need to re-run `vegastack skills install --force` after each `npm i -g @vegastack/cli@latest` to pick up CLI updates. Enabling Developer Mode is recommended.\n\n### `vegastack tf` exits 4 (BundleMissing)\n\nThe bundle is missing from disk. Either the postinstall didn't complete, or `VEGASTACK_BUNDLE_DIR` is pointed somewhere wrong. Run `vegastack doctor` for the diagnosis, then `vegastack install` to fix.\n\n### `npx @vegastack/cli` doesn't have a bundle\n\n`npx` skips postinstall. For full functionality, `npm i -g @vegastack/cli` first. `npx` will work for the skill-management commands (`vegastack skills ...`) but not for `vegastack tf`.\n\n## Related\n\n- [PORT-ROADMAP.md](PORT-ROADMAP.md) — v0.2 plan: native TypeScript discover, enrichment, common-query cache.\n- [STYLE.md](STYLE.md) — style + design guide for code reviewers.\n- [CONTRIBUTING.md](CONTRIBUTING.md) — PR workflow, changeset rules.\n- [SECURITY.md](SECURITY.md) — threat model + vulnerability disclosure.\n\n## License\n\n[MIT](LICENSE) © Vegastack Inc.\n",
  "bytes": 22361,
  "sha": "3cf4f8a21ebd26e928a606eceed0471622bb230a7412a4523fe28a53a4c9737c",
  "repo_slug": "vegastack/vegastack-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_vegastack_vegastack_cli_85c648e0/readme"
}