Installation

You consume Alloy as published packages - you never clone or install its source repo. The CLI ships as @engineering11/alloy-cli, run through npx; the corpus and the MCP server ship as their own packages. Everything below serves published corpus-v* versions only.

Prerequisite: the @engineering11 registry scope

The packages are private, under the @engineering11 scope. Clients resolve them from Cloudsmith with the entitlement token from their onboarding email; Engineering11 engineers resolve them from GitHub Packages with a read:packages token. Either way it is a token in your environment plus a two-line global ~/.npmrc - Prerequisites has both variants, the CI form, and the failure table.

Verify before anything else:

npm view @engineering11/alloy-cli version

A version number means you are set. E401 points at the token; E404 at the scope line or a registry host that does not match your credential.

Using Foundry? npx @engineering11/e11-foundry@latest init asks what agents should know about and runs the Alloy commands on this page for you; pick This codebase + the Engineering11 platform to draw on the Engineering11 foundation. Its Get started page walks the four answers.

Document your own repo: one command

The common case - your repo hosts its own knowledge base, and your agent drives everything. One command stands it up:

npx @engineering11/alloy-cli@latest init

alloy init has nothing to choose: it creates this repo's knowledge base under .alloy/, vendors the four agent skills (alloy, alloy-survey, alloy-corpus, alloy-campaign) into your repo, and registers the MCP server. It consumes nothing external. The skills land in .claude/skills/ by default; --ide cursor,codex,opencode targets other harnesses (comma-separable). Resume-safe: every step skips if already done.

Skills only (an existing knowledge base, or a fresh harness): npx @engineering11/alloy-cli skills install [--ide ...]. No-clobber by default, so a re-install never discards local tweaks; --force overwrites.

Then start a fresh agent session and follow the Quick start.

Draw on a shared knowledge base

A fresh knowledge base sees only itself. To read knowledge another repo publishes - for instance the Engineering11 foundation - declare it as a dependency:

npx @engineering11/alloy-cli add @engineering11/alloy

alloy add records the dependency in your corpus manifest, pins the exact resolution in the committed .alloy/corpus.lock, and fetches it into ~/.alloy/cache. On a fresh clone or in CI, alloy sync restores the committed lock into the cache. Package and git locators, qualified keys, and the scope line are covered in Add shared knowledge.

Two more access paths sit alongside the dependency itself:

• The MCP server (canonical agent access) - per repo, in each editor's MCP file. alloy init writes it; npx @engineering11/alloy-cli mcp register adds it to a repo that has none. The entry is pinned to an exact version (npx @engineering11/alloy-mcp@<version>, the version of the CLI that wrote it), so every teammate runs the same server until alloy upgrade moves the pin. Commit the MCP file. Four read-only tools (resolve, search, manifest, matrix) answer from the repo's scope - its own knowledge base plus its locked dependencies - and halt loudly rather than guess. See Integrate with agents.

• An existing node_modules copy - @engineering11/alloy is the corpus package and has no command (the CLI is @engineering11/alloy-cli). An older setup that installed it into node_modules keeps working while its version equals the lock, because node_modules is one of the places a locked dependency is served from. New setups use alloy add.

Keeping Alloy current

Once a day, any alloy command checks the registry in the background. When a newer alloy-cli is published, the next command prints one line on stderr, at most once a day:

alloy: 1.9.2 installed, 1.10.0 available - run `alloy upgrade`

alloy upgrade brings three things level with the newest release, through the path each was installed by:

• the CLI - npm install -g for a global install, a refreshed npx cache for npx, or the project's own package manager when it is a devDependency;
• the MCP pins - every harness MCP file that names @engineering11/alloy-mcp is re-pinned (restart your editor's MCP server afterwards);
• the vended skills - re-vended from the new release. A skills dir with local edits is named before anything is overwritten.

alloy upgrade              # show the table, then confirm
alloy upgrade --check      # report only: exit 0 current, 1 behind, 2 registry unreachable
alloy upgrade --yes        # apply without asking
alloy upgrade --check --json   # the machine-readable report for installers and agents

With npx @engineering11/alloy-cli@latest you always run the newest CLI; alloy upgrade still re-pins the MCP files and refreshes the skills. A global install (npm i -g @engineering11/alloy-cli) stays on its version until you upgrade it.

Set ALLOY_NO_UPDATE_CHECK=1 to turn the daily check off (it is also off whenever CI is set). Tools that run alloy and capture its output should set it so the nudge never lands in their stderr. The check keeps its state in ~/.alloy/update-check.json; ALLOY_HOME moves that directory, along with the cache and telemetry under it.

Which one do I need?

You want to...	Use
Document your own repo with your agent	alloy init, then the Quick start
Draw on a shared knowledge base another repo publishes	alloy add <name>, plus the MCP server for agent access
Restore the committed dependencies on a fresh clone or in CI	alloy sync
Keep an older node_modules setup working	keep its version equal to the lock, or move it to alloy add
Bring the CLI, MCP pins and skills to the newest release	alloy upgrade