getaidex

The official Aidex project initializer.

npx getaidex init

Run from the root of a frontend project, getaidex init detects which framework you're using, recommends the matching Aidex Admin integration package, and shows you exactly what would change in package.json before touching anything. Nothing is installed or written until you explicitly confirm.

getaidex is deliberately an unscoped package name, distinct from every @aidex/* package in this monorepo — it's a one-off npx tool, not a dependency your project installs.

Why not npx aidex init?

The unscoped npm name aidex already belongs to an unrelated package. getaidex (matching the github.com/getaidex organization) is the initializer's real, permanent name — the only supported command is npx getaidex init.

Quick start

npx getaidex init

The flow is always the same:

Detect → Recommend → Preview → Confirm → Update package.json → Show install command

1. Detect — reads package.json in the current directory and checks its dependencies/devDependencies/peerDependencies for a known frontend framework.
2. Recommend — maps the detected framework to the matching @aidex/admin-* package(s), explaining why each is recommended.
3. Preview — prints the exact dependency lines that would be added. Nothing is written yet.
4. Confirm — asks Apply these changes? [y/N]. Only an explicit y or yes proceeds.
5. Update package.json — adds the recommended packages to dependencies, preserving every other field, value, and key order exactly as they were.
6. Show install command — detects your package manager from its lockfile and prints the command to run. getaidex never runs it for you.

Installing the added dependencies is intentionally left to you — running npm/pnpm/yarn/bun on your behalf is not something this tool does.

Supported frameworks

| Detected | Recommends | |---|---| | React (react in any dependency section) | @aidex/admin-react + @aidex/admin-theme | | Angular (@angular/core) | @aidex/admin-angular + @aidex/admin-theme | | Vue (vue) | @aidex/admin-vue + @aidex/admin-theme | | Web Components (lit, lit-element, or lit-html) | @aidex/admin-elements + @aidex/admin-theme |

Detection reads package.json only — no source files, no AST parsing. React's signal is react itself; react-dom, if present, is reported alongside it but isn't required on its own. Web Components detection looks specifically for a Lit package — a project with no recognized framework signal at all is reported as unknown, never guessed as Web Components just because nothing else matched.

@aidex/admin is the framework-agnostic base every adapter above already depends on — installing any one of admin-react/admin-angular/ admin-vue/admin-elements pulls it in automatically, so getaidex never recommends installing it directly.

Two more outcomes are handled explicitly, never as a crash:

• No package.json found — getaidex init reports the path it checked and exits cleanly.
• package.json exists but isn't valid JSON — the parse error is shown, along with the path.

Example

Run in a React project with react and react-dom already installed:

$ npx getaidex init
Aidex Project Setup

✓ React detected
  Found react ^19.1.0 in dependencies
  Found react-dom ^19.1.0 in dependencies

Recommended Aidex integration:

  @aidex/admin-react
  Detected via react (dependencies), react-dom (dependencies). @aidex/admin-react provides useAdmin() and the AI Control Center components (Overview, RecentExecutions, RoutingDetail, GuardrailActivity, and more) for React.

  @aidex/admin-theme
  @aidex/admin-theme supplies the CSS design tokens the AI Control Center components render with.

@aidex/admin-react already depends on @aidex/admin — it installs automatically and does not need to be added separately.

Proposed package.json changes:

  + "@aidex/admin-react": "^1.1.0"
  + "@aidex/admin-theme": "^1.1.0"

Apply these changes? [y/N] y

Updated package.json:

  + "@aidex/admin-react": "^1.1.0"
  + "@aidex/admin-theme": "^1.1.0"

Run the following to install:

  pnpm install

Running getaidex init again afterward detects that both packages are already installed and reports:

✓ Aidex is already configured for this project.
No changes required.

Safety

• Default is no. Pressing Enter, typing anything other than an explicit y/yes, or pressing Ctrl+C during the prompt all decline — package.json is left byte-for-byte unchanged.
• Nothing is written before confirmation. Detection and the preview are both read-only.
• No package manager is ever executed. getaidex never shells out to npm, pnpm, yarn, or bun — it only prints the command you'd run.
• Only genuinely new dependencies are added. A package already present in any dependency section is left untouched, never duplicated or downgraded.
• Existing package.json content is preserved. Every other key, value, and the original key order survive the update unchanged; only the recommended package names are appended to dependencies.
• Safe to rerun. Once everything recommended is already installed, getaidex init reports that Aidex is already configured and makes no further changes.

Package manager detection

getaidex init looks for a lockfile in the project root to decide which install command to print:

| Lockfile | Command printed | |---|---| | pnpm-lock.yaml | pnpm install | | package-lock.json | npm install | | yarn.lock | yarn install | | bun.lockb | bun install |

If none of these are found, a generic instruction is printed instead of guessing. In every case, the command is printed only — never executed.

Requirements

Node >=20.19.0

Development

This package lives in the Aidex monorepo alongside every @aidex/* package, but is published to npm under its own unscoped name, getaidex.