Build a distribution

An Aura distribution is a small executable that fixes its branding, plugins, registry privileges, and defaults at build time. Use one when a company wants a trusted acmedev command instead of asking every developer to assemble plugins locally.

Prerequisites

• Use Node.js 24, pnpm, TypeScript, and Bun 1.3.14.
• @tryaura/aura-cli, @tryaura/aura-sdk, and @tryaura/aura-testkit pinned to the same version.
• A package or workspace for the distribution source.

Compose the command

1. Install the public packages at one version.

   pnpm add @tryaura/aura-cli@0.5.4 @tryaura/aura-sdk@0.5.4 @tryaura/aura-testkit@0.5.4
   pnpm add --save-dev typescript @types/node

2. Create the entry point.

   src/main.ts

   #!/usr/bin/env node
   import { runCli, type CliDistro } from "@tryaura/aura-cli";
   import { OFFICIAL_PLUGINS, OFFICIAL_REGISTRY_OPTIONS } from "@tryaura/aura-cli/plugins";
   
   const distro: CliDistro = {
     branding: {
       command: "acmedev",
       displayName: "Acme Dev",
       description: "Keep Acme coding agents on the same configuration",
       docsUrl: "https://engineering.acme.example/acmedev",
       version: "0.1.0",
     },
     plugins: [...OFFICIAL_PLUGINS],
     registry: OFFICIAL_REGISTRY_OPTIONS,
   };
   
   await runCli(distro);

3. Run and typecheck the source command.

   pnpm exec tsc --noEmit
   bun run src/main.ts --help
   bun run src/main.ts check --json

4. Add one trusted private plugin after the official list when you need internal adapters, checks, presets, or content.

   src/main.ts

   plugins: [...OFFICIAL_PLUGINS],
   plugins: [...OFFICIAL_PLUGINS, internalPlugin],

5. Register a distribution command when an internal workflow belongs beside setup, check, and undo.

   src/main.ts

   commands: [syncCommand],

6. Ship it when the source command is right: asset staging, binary compilation, smoke testing, and self-updating releases.

What just happened?

runCli supplied the command shell, while the distribution supplied the product identity, the only plugins the process can load, and any commands of its own. End users install the resulting command; Aura does not discover runtime plugins from their machine.

Distribution defaults are the lowest configuration layer. A selected preset, repository preset, manifest, and command-line flags can override them in that order.

Compiled code is not sandboxed

Every compiled plugin and registered command runs with the full privileges of the distribution. Pin and review private code like production dependencies, and keep registry credentials in build CI only.

Common failures

Symptom	Cause	Fix
Plugin registration fails at boot	IDs, versions, API version, or registry privileges conflict	Fix the named contribution; Aura refuses ambiguous registries.
The run exits 3 naming a command word	A registered command word or flag is reserved, malformed, or duplicated	Fix every listed problem; Aura reports them in one message.
A source build works but the binary loses content	Bun did not receive every Markdown or JSON asset as an entrypoint	Derive asset entrypoints from the content directory and smoke-test the binary.
Package types disagree	The CLI, SDK, and testkit versions drifted	Pin all three public packages to the same exact release.

Next steps

Ship a distributionAdd an adapter, content, a preset, telemetry, compilation, and smoke coverage.

Understand pluginsChoose contribution slots and follow registry and trust rules.

Register a commandAdd a top-level command with flags, an injected environment, and telemetry.

Add distribution updatesPublish verified standalone releases from GitHub or a signed manifest.