geenius-xli

Internal operations CLI for cross-workspace Geenius maintenance.

geenius-xli is the internal operations CLI for the Geenius ecosystem. It is published to npm for easy installation and self-updates. Use it for commands that operate across geenius-apps/, geenius-boilerplates/, and geenius-packages/: batch installs and builds, golden-standard audits, Convex codegen, analytics, boilerplate runtime control, and guarded publish planning.

Installation

pnpm add -g geenius-xli

This installs both geenius-xli and gxli globally:

gxli --version
gxli --help

Updating

gxli update --check
gxli update
gxli self-update --check
gxli self-update

Bare gxli update and gxli self-update both update geenius-xli itself. Use gxli update packages, gxli update apps, gxli update boilerplates, or gxli update all for workspace dependency updates.

Development

pnpm install
cp .env.example .env
pnpm build
node dist/index.js --help

Architecture

• src/index.ts: Commander entrypoint and command registration
• src/commands/: one module per command family
• src/lib/env.ts: validated environment variables
• src/config.ts: .geenius-xli/config.json inference and validation
• src/lib/workspace.ts: apps/packages/boilerplates discovery across the workspace
• src/lib/dep-sync.ts: pure dependency synchronization engine (used by sync-deps)
• src/lib/dep-audit.ts: pure dependency audit engine (used by audit-deps)
• src/lib/output.ts: human and JSON rendering with a stable automation envelope

geenius-xli auto-creates .geenius-xli/config.json at the workspace root on first run. When config is missing, it infers sane defaults for:

• geenius-apps
• geenius-boilerplates
• geenius-packages

Environment Variables

All xli-specific environment variables are optional and validated through Zod.

| Variable | Required | Description | | --- | --- | --- | | GEENIUS_XLI_ROOT | No | Override workspace-root detection. Use when running xli from outside the Geenius workspace. | | GEENIUS_XLI_CONFIG_DIR | No | Override the config directory location. Resolved relative to the workspace root. | | GEENIUS_XLI_NONINTERACTIVE | No | Force non-interactive behavior for scripts and tests. Accepts true/false, 1/0, yes/no, on/off. | | GEENIUS_XLI_SKIP_GITIGNORE_UPDATE | No | Prevent xli from adding .geenius-xli/ to the workspace .gitignore. Useful for smoke tests. | | GEENIUS_XLI_JSON | No | Default all command output to the JSON envelope used by automation. |

Command Reference

Every command supports --json and returns the stable envelope:

{
  "ok": true,
  "command": "list packages",
  "summary": "Listed 42 package(s).",
  "data": {}
}

Discovery

gxli greet
gxli info
gxli list packages
gxli list apps
gxli list boilerplates

Install, Update, Build

gxli install packages admin
gxli install apps cloud
gxli install boilerplates react-convex --tier studio
gxli install all

gxli update packages admin
gxli update apps gtm
gxli update boilerplates solidjs-convex --tier studio
gxli update all

gxli build packages alpha
gxli build apps cloud
gxli build boilerplates react-convex --tier studio
gxli build all

Audits

gxli audit
gxli audit --package admin teams --detailed
gxli audit --format markdown --output reports/packages.md
gxli audit parity
gxli audit pis

gxli audit supports:

• --package <names...>
• --detailed
• --format table|json|markdown
• --strict
• --output <file>

Testing

gxli test packages
gxli test packages --task lint:pub test:types
gxli test packages --package alpha beta

Publishing

gxli publish
gxli publish --package alpha beta
gxli publish --mode publish --yes

Default mode is dry-run. Live publishing requires both --mode publish and --yes, and later publish phases are aborted if an earlier phase fails.

Benchmarking And Analytics

gxli benchmark
gxli benchmark http://127.0.0.1:4173
gxli analytics loc
gxli analytics loc --output reports/loc.md
gxli analytics reports
gxli analytics reports --output reports/summary.md

gxli analytics reports scans the workspace for .gap-*-report.json, .fix-*-report.json, and .phase-*-report.json files and writes a consolidated Markdown summary.

Convex Codegen

gxli codegen generate
gxli codegen generate geenius-ai-workflow
gxli codegen check
gxli codegen clean geenius-ai-workflow
gxli codegen list
gxli codegen version

Self-Update

gxli update               # Check for updates and install if available
gxli update --check       # Only check, don't install
gxli self-update          # Alias for bare update
gxli self-update --check

MCP Mode

gxli mcp

gxli mcp is reserved for MCP stdio mode and exits with MCP_UNSUPPORTED at v1.

Boilerplate Runtime Control

gxli run studio react convex
gxli run all tailwind --attach
gxli stop
gxli stop all
gxli stop ports

gxli run launches runnable Node-based boilerplates in tmux sessions. Use --attach when you want the CLI to attach immediately after creating the session.

Dependency Synchronization

gxli sync-deps              # Dry-run: show what would change
gxli sync-deps --write      # Apply changes to disk
gxli sync-deps --json       # Structured JSON output

Synchronises cross-cutting dependency versions (react, react-dom) across all packages, apps, and boilerplates. Walks all three ecosystem tiers:

• geenius-packages/* (36 packages + nested packages/ and apps/)
• geenius-apps/* (standalone applications)
• geenius-boilerplates/{pronto,lancio,studio}/* (boilerplate templates)

Version strategy:

• dependencies/devDependencies: caret ranges (^19.2.6) — updatable via pnpm update
• pnpm.overrides: exact pins (19.2.6) — deterministic resolution across sub-packages

The engine skips workspace:* and link: references automatically and is idempotent (second run always produces zero changes).

Dependency Audit

gxli audit-deps                     # Audit only: show all issues
gxli audit-deps --fix-latest        # Resolve "latest" → "^x.y.z"
gxli audit-deps --fix-links         # @geenius/* → link:/workspace:*
gxli audit-deps --fix-pinned        # "1.2.3" → "^1.2.3"
gxli audit-deps --fix-all           # Apply all three fixes at once
gxli audit-deps --json              # Structured JSON output

Audits dependency version hygiene across the entire ecosystem and detects three categories of issues:

| Category | What it detects | Fix | | --- | --- | --- | | [LATEST] | Dependencies set to "latest" | Resolves via node_modules or npm registry → "^x.y.z" | | [GEENIUS] | @geenius/* packages with version strings (should be link: or workspace:*) | Computes correct path reference | | [PINNED] | Exact versions like "1.2.3" without a caret | Converts to "^1.2.3" |

Fix flags are composable — e.g. --fix-latest --fix-links applies two fixes without touching pinned versions. --fix-all is a shortcut for all three.

The engine automatically excludes:

• workspace:* and link: references (already correct)
• peerDependencies (intentional version flexibility)

Scripts

| Script | Description | | --- | --- | | pnpm dev | Rebuild the CLI in watch mode with tsup. | | pnpm build | Build the ESM CLI into dist/. | | pnpm start | Run the built CLI from dist/. | | pnpm typecheck | Run TypeScript checks without emitting files. | | pnpm lint | Run Biome across the package sources, configs, and docs. | | pnpm format | Apply Biome formatting to the checked package files. | | pnpm test | Run the Vitest suite. | | pnpm test:coverage | Run the Vitest suite with the required coverage thresholds. | | pnpm test:smoke | Smoke test the built CLI help/version and core --json commands. | | pnpm smoke | Backward-compatible alias for pnpm test:smoke. | | pnpm clean | Remove build output and generated local caches. |

Verification

From the package root:

pnpm typecheck
pnpm lint
pnpm test
pnpm test:coverage
pnpm build
pnpm test:smoke

From the workspace root:

pnpm --dir geenius-apps/geenius-xli typecheck
pnpm --dir geenius-apps/geenius-xli lint
pnpm --dir geenius-apps/geenius-xli test
pnpm --dir geenius-apps/geenius-xli build