Scaffold, configure, validate, and operate EAI applications from a developer terminal.

The CLI gives teams a supported path for application setup, authentication, tenant selection, runtime validation, resource management, and deployment readiness. It keeps platform access behind authenticated commands and public-safe diagnostics, so developers and AI coding agents get useful next steps without exposing private infrastructure details.

This package is intended for public npm installation in enterprise developer workstations, CI agents, Codespaces, and other controlled engineering environments.

This repository is the public source for the EnterpriseAI CLI. The README is the fast path for developers who want to install the tool, understand what it does, and find the maintained documentation.

Public-readiness rule for maintainers: everything committed here must be safe for a public audience. Do not commit secrets, customer data, private tenant details, local .env files, unpublished internal architecture notes, private environment URLs, or temporary build output.

Generated Gofer specs, memory files, logs, checkpoints, and local runtime state are intentionally ignored. The committed .specify directory contains only the reusable scripts and templates needed by eai init and eai gofer refresh.

Recommended install:

npm install -g eai-cli

Canonical package:

npm install -g @enterpriseai/cli

Static registry fallback:

npm install -g @enterpriseai/cli --@enterpriseai:registry=https://eai-support.github.io/eai/registry/

Persistent static fallback setup:

npm config set @enterpriseai:registry https://eai-support.github.io/eai/registry/ --location=user
npm install -g @enterpriseai/cli

If you are validating the generated registry from a local checkout of this repo, install the tarball instead of the packument file:

npm install -g ./docs-site/static/registry/-/@enterpriseai/cli-latest.tgz

docs-site/static/registry/@enterpriseai/cli is the registry metadata file. It is not an installable package directory.

# 1. Run the guided first-time setup
eai create my-app
cd my-app

# `eai create` checks local tooling, signs you in, confirms the signup
# workspace, creates the app, installs dependencies, verifies Gofer, and
# checks builder readiness. Use `eai start` to open a supported AI workspace when
# it finishes. Pass `--no-install` to skip the install and run
# `npm install` yourself.

# 2. For an existing login or automation, use the lower-level commands:
eai whoami
eai tenant select

# 3. Create child tenants only when you need them
#    `eai tenant create --parent <id>` now creates the tenant record,
#    attempts first-admin bootstrap for the current login, and only marks
#    the tenant usable after direct tenant-admin membership is confirmed.
#    The child home region defaults to the parent region; pass
#    `--home-region au|ca|eu` when the child must use another region.

# 4. Sync project environment if your app needs local configuration
eai env pull --include-secrets

# 5. Define your data model
#    Edit src/eai.config/object-types.ts
#    Keep name PascalCase and declare an exact lowercase kebab-case slug.
#    Relationship targets use the target's exact stored slug.

# 6. Validate, inspect, publish, and verify
eai types validate
eai types diff
eai types seed
eai resources schema --format json

# 7. Start developing
eai dev

eai create installs Gofer AI terminal assets by default. New app repos include Claude commands and agents, Codex skills, Gemini commands, Copilot prompts and CLI skills, and the .specify commands/scripts/templates/hooks required to run the Gofer pipeline. Use eai create my-app --no-gofer only when you need a bare scaffold. eai init remains available as the low-level, backwards-compatible scaffold command. Use eai create my-app --skip-onboarding when you want the old init prompts without the first-run checks.

By default, eai create my-app creates a new ./my-app folder. If you already created and entered a project folder, run eai init, enter the app name, and answer yes when asked to use the current folder. For automation, pass --current-dir with the kebab-case app name. Current-folder init preserves unrelated existing files and Git metadata, and updates files that are part of the generated scaffold.

All commands support these global flags:

The bundled default template is pinned to the latest eai-app-template main commit captured when this CLI release was cut. Use --from to override it with a different repository or a local template path.

Codespaces and other remote dev environments can keep the standard localhost callback by forwarding a fixed callback port from the Codespace to your local machine:

# Local machine, keep this running in a separate terminal
gh codespace ports forward -c <codespace-name> 3476:3476

# Codespace terminal
eai login --callback-port 3476

eai login --callback-port <port> still uses http://localhost:<port> for the OAuth callback; it just pins the port instead of choosing a random one. That keeps the public Entra app registration unchanged while allowing your local machine to tunnel the callback into the Codespace.

Object Types keep two different identifiers. The source/model name is PascalCase, such as BoardAppUser. The explicit persisted and transport slug is exact lowercase kebab-case, such as board-app-user. Do not convert every field to the same case.

Generated or persisted linkTypes[].targetObjectType, runtime target_type, resource command arguments, path parameters, and governed v4 query fields use the exact stored slug. A same-manifest PascalCase relationship target is only source shorthand: the CLI resolves it through the target's declared slug before diff or seed and rejects unresolved names. Historical stored slugs are authoritative and must never be silently re-derived or renamed.

{
  name: "BoardAppMembership",
  slug: "board-app-membership",
  linkTypes: [
    {
      name: "user",
      targetObjectType: "board-app-user",
      cardinality: "many-to-one",
    },
  ],
}

Use this publication sequence: eai app provision, eai types validate, eai types diff, eai types seed, then eai resources schema.

In every command below, <type> and each value passed to --types mean an exact published Object Type slug, not its PascalCase model name. App feature code should use useResources or client.resources so the shared SDK owns route construction.

Use named commands first for normal workflows. eai publicapi is the advanced V4-only surface for route families that do not yet have a polished command, such as geo, realtime, platform administration, integrations, or DAISY-specific diagnostics. It still uses your current login and tenant context, and PublicAPI still enforces platform tenant authorization.

The runtime contract lives in eai.runtime.json. It declares required environment variable names, required secrets, health/runtime endpoints, Auth.js callback path, tenant/workflow key patterns, user-delegated BFF access, and post-deploy smoke tests. It is host-neutral: Vercel, Docker, AWS, Azure, Kubernetes, VM-style hosts, and internal demo environments should translate the same contract into their provider-specific env and secret setup.

eai deploy doctor deliberately does more than /health. A deployment can have /health returning 200 and still fail because Auth.js providers are missing, the Entra callback URL is wrong, tenant/workflow config is empty, a route is trying to use unsupported app-only data-plane access, PublicAPI rejects authorization, or the app runtime is throwing errors.

eai tenant create now distinguishes these states:

• created: the tenant document exists
• bootstrapped: the CLI successfully called the constrained first-admin bootstrap flow for a child tenant
• usable: a refreshed membership check confirmed the current login now holds direct tenant-admin on that tenant

For child tenants, the CLI only auto-selects the new tenant when usable is true. If bootstrap is blocked or downstream membership confirmation has not landed yet, the command leaves the active tenant unchanged and reports that explicitly.

The first-admin bootstrap path is intentionally narrow:

• the caller must already be tenant-admin on the direct parent tenant
• the target must be an immediate child of that parent
• the child must not already have a tenant admin
• parent child allowance is enforced from limits.tenants

For existing child tenants that were created before the bootstrap completed, a parent tenant admin can run:

eai tenant bootstrap-admin --parent <parent-tenant-id> --child <child-tenant-id>

By default this bootstraps the current login. To repair another known parent member, pass --user-oid <entra-user-oid> and optionally --user-email <email>.

Use eai user invite for normal "add this person to a tenant" and "make this person a tenant admin/member" requests. The command calls the V4 tenant member invite/add flow and can assign these base roles:

• tenant-viewer
• tenant-staff
• tenant-builder
• tenant-admin

Common examples:

eai user roles --tenant <tenant-id> --format json
eai user invite --email user@example.com --tenant <tenant-id> --role tenant-viewer
eai user invite --email admin@example.com --tenant <tenant-id> --role tenant-admin
eai user list --tenant <tenant-id> --search admin@example.com --format json

If eai user invite fails with a 5xx or EXTERNAL_SERVICE_ERROR, do not guess or edit the database directly. Run:

eai errors explain user_invite_external_service_existing_member --format json
eai user list --tenant <tenant-id> --search <email> --format json

If the person already exists as a direct tenant member and you approve the role change, repair the role through EAI CLI and verify read-back:

eai user role set --tenant <tenant-id> --member-id <member-id> --role tenant-admin --format json
eai user list --tenant <tenant-id> --search <email> --format json

The affected app user may need to sign out and sign back in because Auth.js session or JWT role data can be cached.

eai tenant bootstrap-admin is not a general "make this user an admin" command. It is only for repairing first tenant-admin access on an existing immediate child tenant when the caller is already tenant-admin on the direct parent.

Developer Terminal                    EAI Platform
──────────────────                    ────────────
eai login ──────────────────────────→ Entra CIAM (browser PKCE + localhost callback)
eai tenant select ──────────────────→ Current-user memberships → active tenant context
eai env pull ───────────────────────→ Azure App Config + Key Vault
eai types seed ─────────────────────→ Platform API → Type Registry
eai resources list <object-type-slug> → Platform API → Data Service
eai workflow status ────────────────→ Platform API → AI runtime readiness
eai chat stream ────────────────────→ Platform API → AI Service
eai docs classify ──────────────────→ Platform API → AI Service
eai runtime validate ────────────────→ eai.runtime.json → local contract evidence
eai deploy env ──────────────────────→ eai.runtime.json → provider env/secret checklist
eai deploy doctor ───────────────────→ deployed app URL → black-box runtime checks
eai deploy trigger ─────────────────→ GitHub Actions → deployment workflow

The CLI authenticates via browser-based authorization code flow with PKCE, stores tokens locally in ~/.eai/, persists the active working tenant from your tenant-admin memberships, and calls the platform API directly with a Bearer token. .env.local is still available for project runtime configuration, but tenant selection for CLI platform commands comes from eai login and eai tenant select.

Runtime workflow checks are intentionally public-safe. They tell you whether a workflow key is available, operator_required, paid_upgrade_required, rate_limited, blocked, unsupported, or not ready without exposing private platform topology. Use eai workflow request <key> when the platform reports operator_required.

The CLI uses structured error guidance for consistent human and AI-agent recovery:

• E001-E099: Project errors (not in EAI project, config missing)
• E100-E199: Auth errors (not logged in, token expired)
• E200-E299: Platform errors (API unreachable, resource not found)
• E300-E399: Validation errors (invalid schema, missing field)

Error output explains why the error may have happened, what read-only diagnostics to run first, what mutating eai commands can fix it, and when to stop retrying.

✗ Not logged in.

Why this might happen:
- The CLI does not have a usable local sign-in token.
- The token may have expired or been created for a different local profile.

Try next:
1. eai whoami [read-only]
   Show the current login and active tenant status.
2. eai login [changes state]
   Authenticate with the EAI identity flow.

Error code: E101
Reason: not_logged_in

JSON output keeps the legacy suggestion field and adds structured guidance for AI agents:

{
  "error": {
    "code": "E101",
    "message": "Not logged in",
    "suggestion": "Run `eai login` to authenticate with the platform",
    "guidance": {
      "reasonCode": "not_logged_in",
      "why": ["The CLI does not have a usable local sign-in token."],
      "diagnostics": [{ "command": "eai whoami", "mutates": false }],
      "fixes": [{ "command": "eai login", "mutates": true }]
    },
    "exitCode": 1
  }
}

Use eai errors explain <code-or-reason> for the release-aligned explanation:

eai errors explain E101
eai errors explain tenant_authorization_incomplete --format json
eai errors explain user_invite_external_service_existing_member --format json
eai errors explain app_token_tenant_context_required --format json

Use app_token_tenant_context_required when platform user lookup or membership prerequisite calls return MISSING_TENANT or "Tenant context required for app tokens"; retry tenant-scoped V4 platform routes before changing tenant members, role definitions, Entra configuration, databases, or cloud portals.

Most data-returning commands that advertise --format <format> support --format json for automation. Check eai --describe or command help before scripting a subcommand; status-only commands such as eai whoami and quick eai verify are plain text today.

# Get JSON output
eai resources list board-app-user --format json

# Parse with jq
eai tenant list --format json | jq '.tenants[] | .slug'

# Use in scripts
if eai verify calls --format json | jq -e '.summary.failed == 0' > /dev/null; then
  echo "Platform contracts are healthy"
fi

The --describe flag outputs the CLI command structure as JSON Schema, enabling AI agents and automation tools to discover capabilities at runtime:

eai --describe        # Describe all commands
eai types --describe  # Describe types subcommands

For AI agents that need to use eai without extra instructions, start with the built-in operating guide:

eai agent guide --format json

The same guide is embedded in eai --describe as agentGuide. It tells agents to prefer structured output, run read-only diagnostics before fixes, call eai errors explain <code-or-reason> --format json after failures, use named commands before raw publicapi calls, and stop when retry or escalation conditions match.

To test whether a weak agent can discover that behavior without EAI-specific prompt instructions, run the built-in discovery eval:

npm run build
npm run eval:agent-discovery -- --json

The default regex-small agent is intentionally limited: it starts from generic help/describe output, parses visible error codes or reason codes, and only runs commands it discovers from the CLI output. Use --agent-command <cmd> to plug in a real model runner that accepts the eval JSON turn on stdin and returns a JSON decision.

Every eai init project includes the repo-local Gofer assets needed by the AI terminals used in this workspace:

The shared workflow artifacts live under .specify/: commands, scripts, templates, hooks, memory, logs, and generated feature specs. Runtime state is added to .gitignore; command definitions and templates are committed with the app.

eai update keeps the local EAI toolchain current. It checks the installed CLI against npmjs first, falls back to the public static registry when needed, installs the newer CLI when available, then refreshes safe Gofer-managed files in the current EAI project. It does not blindly rewrite template files or UI components inside an existing app repo.

Use these commands for the full maintenance loop:

# See whether a newer CLI release, Gofer refresh, or template review is available
eai update --check

# Same report through the broader doctor command
eai doctor --check-updates

# Preview safe Gofer-managed asset updates for the current repo
eai gofer refresh --check

# Apply safe Gofer-managed file updates, with backups and conflict detection
eai gofer refresh

# Preview app-template and UI component drift before copying changes manually
eai template check

Important boundaries:

• eai update --check is read-only. eai update may write only Gofer-managed files in an EAI project.
• eai gofer refresh prefers the latest public eai-gofer release at runtime, so Gofer asset updates do not require a new eai CLI release. If the latest release cannot be reached or prepared, it falls back to the bundled snapshot.
• eai gofer refresh manages the Gofer-owned surfaces copied by eai init such as .specify/, .claude/, .agents/skills/, .gemini/, and generated Copilot Gofer files.
• It writes or updates .eai-manifest.json so future refreshes can detect local edits and avoid overwriting them accidentally.
• If a tracked managed file has local edits, refresh leaves it untouched unless you explicitly pass --force, and even then it backs the file up first.
• eai template check previews file-level drift against the app-template main snapshot pinned in the installed CLI release and highlights which files are new versus which need manual review, including likely UI paths under src/app and src/components.
• Template or UI component changes are not auto-merged into existing repos yet. Copy additions first, then diff/review existing files that eai template check marks for manual review.
• During normal interactive CLI use, if the CLI has already cached that a newer release is available, it can ask whether to run eai update immediately. That prompt is suppressed for CI, non-TTY, --describe, --format json, and --json output.

git clone https://github.com/eai-support/eai.git
cd eai
npm install
npm run build        # Compile TypeScript
npm run dev          # Watch mode
npm run typecheck    # Type check without emitting
npm run lint         # Run ESLint

The documentation site lives in docs-site/ and renders the source content from .tech-docs/, the scenario library, and the generated command/API reference. GitHub Pages is the public deployment target for both the documentation site and the static npm registry fallback used by the install flow.

The Deploy Docs workflow builds docs-site/ on main when documentation, release-doc, registry, or LLM-help assets change. It uploads docs-site/build with the official GitHub Pages artifact action and deploys it to the github-pages environment.

Pages serves these public artifacts:

• /docs/ and /scenarios/ — documentation and scenario library
• /registry/ — static npm registry fallback metadata and tarballs
• /llms.txt, /llms-full.txt, and /cli-help.txt — release-facing AI/help surfaces generated from the current CLI

Releases are managed with release.sh. It validates the release candidate locally, bumps the version, refreshes the release-facing docs/help surfaces, regenerates the static registry fallback artifacts, pushes main plus the annotated tag, waits for GitHub Actions to publish the npmjs packages and create the GitHub release, waits for the docs deployment that updates the static registry fallback, and then verifies npmjs plus the public static registry expose the new version.

./release.sh <patch|minor|major> "Release message"

Examples:

./release.sh patch "Fix auth token refresh bug"
./release.sh minor "Add bulk resource import command"
./release.sh major "New config format, breaking changes to types CLI"

• Run from a clean main checkout
• gh must be installed and authenticated

The script runs npm run release:check, which covers the main $6_gofer_validate style release gates:

1. Verifies you're on main with a clean working tree
2. Pulls latest and installs dependencies (npm ci)
3. Typecheck (tsc --noEmit)
4. Lint (eslint)
5. Build (tsc)
6. Test (vitest run)
   • Focused SRP CLI evidence also runs as npm run test:eai-cli:ci in GitHub Actions check ci/eai-cli-tests
7. Smoke tests — eai --version, eai --help, eai update --check, and the shipped command groups
8. Docs site build
9. Release-facing docs/help generation (llms.txt, llms-full.txt, cli-help.txt)
10. Registry artifact generation (npm pack + generate-registry.cjs)
11. The eai-cli npm alias package builds and installs the eai command
12. Static-registry fallback metadata stays aligned with the documented install flow
13. Full e2e smoke traceability stays aligned with eai --describe

release:check always validates the full command/CRUD traceability table in .tech-docs/full-e2e-smoke-traceability.md. The destructive live suite is opt-in because it creates a disposable app, publishes Object Types, provisions storage, and CRUDs PostgreSQL, DocumentDB, Blob-backed file, and Search-indexed resources in a dedicated test tenant.

Use a dedicated test user and tenant. Do not paste the password into a chat or commit it to the repo; store it in your shell only for the run, or in GitHub Actions secrets.

export EAI_RELEASE_FULL_E2E_SMOKE=1
export EAI_E2E_TEST_PROFILE=test
export EAI_E2E_TEST_USERNAME='<dedicated-test-user-email>'
export EAI_E2E_PARENT_TENANT_ID='<dedicated-test-tenant-id>'

# Authenticate the profile before the run:
eai --profile "$EAI_E2E_TEST_PROFILE" login

# Or provide a secure bootstrap command that leaves whoami working:
export EAI_E2E_AUTH_COMMAND='<secure-auth-bootstrap-command>'

npm run smoke:eai-full:live

If an external bootstrap command needs a password, pass it through an environment secret such as EAI_E2E_TEST_PASSWORD. The smoke runner redacts password-like values from failures and does not print or persist the password.

1. release.sh bumps the requested semver level
2. It updates the visible .tech-docs/ release metadata to the new version and release message
3. It regenerates docs-site/static/registry/, docs-site/static/llms.txt, docs-site/static/llms-full.txt, and docs-site/static/cli-help.txt
4. It commits the release, creates an annotated vX.Y.Z tag, and pushes main --follow-tags
5. The tag-triggered GitHub Actions Release workflow verifies the committed release docs/help surfaces, publishes @enterpriseai/cli and eai-cli to npmjs with trusted publishing, then creates the GitHub release and attaches the packaged tarballs
6. The Deploy Docs workflow publishes the matching static registry fallback and release-doc bundle to GitHub Pages
7. release.sh waits for both workflows and verifies npmjs plus the canonical @enterpriseai/cli static fallback

If npmjs or the static registry fallback does not converge to the new version, the script exits non-zero so the release is treated as incomplete.

The EAI CLI is also part of SRP release evidence. Repo-local CLI behavior is owned here through ci/eai-cli-tests; deployed read-only CLI schema, error, auth, and preview canaries live in enterpriseaigroup/eai-testing-dev under the eai-cli cross-service surface. Keep prod CLI canaries read-only; preview lifecycle checks must stay explicit and cleanup-backed.

The release path publishes the repository exactly as committed. Bundled Gofer and linked-source refreshes happen separately via npm run sync:gofer / npm run sync:linked-sources and should be committed before you cut a release. At runtime, eai gofer refresh still checks the public latest eai-gofer release and falls back to that bundled snapshot when offline.

Before making or keeping the repository public, run a public-readiness check:

npm run release:check
git grep -n -E "SECRET|TOKEN|PASSWORD|PRIVATE KEY|CLIENT_SECRET|API_KEY|connection string|AccountKey|Bearer "

GitHub secret scanning and push protection should also be enabled for the repository so accidental credential commits are blocked or alerted before they become a public incident.

Helpful maintainer commands:

npm run docs:release-assets
npm run docs:release-assets:check

• npmjs is the primary release and update channel
• Recommended install: npm install -g eai-cli
• Canonical package install: npm install -g @enterpriseai/cli
• Static fallback: npm install -g @enterpriseai/cli --@enterpriseai:registry=https://eai-support.github.io/eai/registry/
• Persistent fallback setup: npm config set @enterpriseai:registry https://eai-support.github.io/eai/registry/ --location=user
• Use eai update to update the installed CLI and refresh safe project assets

Full documentation: https://eai-support.github.io/eai/

93 pages covering getting started, guides, concepts, command reference, 50 industry scenarios, and examples in 7 languages.

• eai types define — interactive Object Type builder
• eai dev --offline — local mock gateway for offline development
• eai tunnel — Cloudflare tunnel for webhook testing
• npmjs install alias (npm install -g eai-cli) with static registry fallback