EAI CLI - Configuration

Overview

For normal public use, the EAI CLI should need very little configuration. After eai login, the CLI uses your signed-in account and selected workspace to route requests automatically. Public documentation must not describe private environment names, endpoint hostnames, internal routing, cloud resources, or platform infrastructure behind the public API.

Use this page for safe, user-facing configuration only:

1. Output and accessibility preferences
2. Project-local app metadata
3. Local files that must not be committed
4. Troubleshooting commands that do not expose infrastructure details

---

Configuration Sources

Configuration is loaded with this public-facing precedence:

Source	Purpose
CLI flags	One-off command behavior, such as JSON output
Environment variables	Generic runtime behavior, such as color handling
eai.config.ts	Optional project metadata
.env.local	Optional developer-local app values
CLI defaults	Built-in public behavior

The CLI may keep local auth and workspace state on your machine after login. Treat that state as private and manage it through CLI commands such as eai login, eai logout, eai whoami, and eai workspace select.

---

Sign-In Context

Most configuration starts with sign-in:

eai login
eai workspace select
eai whoami

eai whoami is the safest way to confirm which account and workspace the CLI is using. If you need to change workspace, run eai workspace select. If you need to clear local sign-in state, run eai logout.

---

CLI Flags

All commands support these public global flags:

Flag	Type	Description	Default
--simple	boolean	Plain text output for screen readers	false
--no-color	boolean	Disable colored output	false
--color	boolean	Force colored output	false
--describe	boolean	Output machine-readable command metadata	false

Data-returning subcommands may also expose --format <format> for machine-readable output. Check eai --describe or the command help before scripting JSON output because status-only commands such as eai whoami are plain text today.

Examples:

eai workspace list --format json
eai workspace list --simple
eai doctor --no-color

---

Environment Variables

Public documentation only describes generic runtime environment variables:

Variable	Description
NO_COLOR	Disable colored terminal output
FORCE_COLOR	Force colored terminal output
EAI_NO_SPLASH	Set to 1 to suppress the startup EAI wordmark
EAI_NO_ANIMATION	Set to 1 to print the startup wordmark without line animation
NODE_ENV	Standard Node.js runtime mode

EAI_NO_SPLASH and EAI_NO_ANIMATION are local terminal preferences read from the CLI process only. They have no App Configuration or infrastructure mapping.

Do not put credentials, tokens, endpoint URLs, or workspace-specific values into committed files. Automation credentials should be stored in your CI provider's secret store and supplied according to your organization's onboarding guide.

---

Project Files

.env.local

File: .env.local in the project root

Purpose: Optional developer-local app values. This file is private to your machine and should not be committed.

Public-safe example:

NEXT_PUBLIC_APP_NAME=My App
NODE_ENV=development

Rules:

1. Keep .env.local in .gitignore.
2. Do not commit tokens, API keys, client secrets, workspace-specific values, or endpoint URLs.
3. Use your deployment provider's secret management for deployed applications.

eai init records the local CLI profile selector as EAI_PROFILE in this ignored file so a reopened app workspace keeps its CLI authentication context. The selection order is an explicit --profile, your shell's EAI_PROFILE, the app-root .env.local selector, then the public default. Named selectors require an existing local CLI profile; a missing profile fails before platform requests. eai env push excludes this selector, and eai env pull excludes it before parsing or resolving cloud references, preserving its local value. Profile credentials and CLI tokens remain outside the app repository.

eai init establishes the .env.local ignore rule before writing credentials. Existing .gitignore and .env.local files must be regular, unlinked files within 1 MiB. The ignore file's content and permissions are preserved when the rule is appended atomically. The generated .env.local replaces an ordinary scaffold file atomically with private permissions; linked credential destinations are refused, including when initializing in the current directory. All subsequent init hydration and provisioning patches use that same protected writer, including client secrets and cloud-secret hydration. Temporary .env.local.eai-*.tmp credential files are ignored as well, so an interrupted initialization cannot leave them eligible for ordinary Git staging. Init file writers use an exclusive lock with no stale-lock takeover. New leaves are published without replacing another file. Existing regular files are rechecked under that lock and replaced atomically; these checks coordinate init writers and detect observed changes, without isolating arbitrary concurrent filesystem changes by the same user. Inspect the files and lock before retrying an interrupted initialization.

Before commands use PublicAPI authentication, a named profile's PublicAPI endpoint must agree with BASE_URL_PUBLIC_API and ROUTING_BOOTSTRAP_PUBLIC_API_URL where configured in the app-root .env.local or your shell. The shell bootstrap is checked even when the project has no BASE_URL_PUBLIC_API. eai login accepts its authentication flags before that check, then rechecks the selected profile and returned token configuration before protected workspace discovery. eai logout clears only the selected local token namespace.

eai env pull and eai env push use Azure CLI authorization independently of your platform workspace role and PublicAPI configuration. They validate the local profile selector without requiring saved platform authentication settings. For an App Configuration identity with data-plane permissions, use Azure CLI's login mode for the command:

AZURE_DEFAULTS_APPCONFIG_AUTH_MODE=login eai env push --label <app-name> --key <key>
AZURE_DEFAULTS_APPCONFIG_AUTH_MODE=login eai env pull --label <app-name>

Configure EAI_APP_CONFIG_STORE for the intended store. Azure CLI defaults to access-key authorization when no auth mode is configured; that mode also requires permission to retrieve the store's access keys.

eai.config.ts

File: eai.config.ts in the project root

Purpose: Optional type-safe project metadata.

Public-safe example:

export default {
  appName: 'My App',
  features: {
    chat: true,
    documents: true,
  },
};

Keep this file free of secrets and environment-specific endpoints.

.eai-manifest.json

File: .eai-manifest.json in the project root

Purpose: Track Gofer-managed files installed by the CLI.

This file is managed by CLI commands such as eai init, eai gofer refresh, and eai doctor --check-updates. Do not edit it manually.

---

Secrets

Never commit secrets. That includes:

1. Access tokens
2. API keys
3. Client secrets
4. Private endpoint URLs
5. Workspace-specific identifiers
6. Generated credentials

For local development, keep private values in ignored local files. For CI/CD and hosted deployments, use the secret store provided by your deployment platform.

---

Configuration Loading Flow

flowchart TB
    Start[Command execution]
    Flags[Parse CLI flags]
    EnvVars[Read generic environment variables]
    EaiConfig[Load eai.config.ts]
    EnvLocal[Load .env.local]
    Defaults[Apply CLI defaults]
    End[Final command settings]

    Start --> Flags
    Flags --> EnvVars
    EnvVars --> EaiConfig
    EaiConfig --> EnvLocal
    EnvLocal --> Defaults
    Defaults --> End

---

Troubleshooting

Not sure which account or workspace is active?

Run:

eai whoami

Need to switch workspace?

Run:

eai workspace select

Need to clear local sign-in state?

Run:

eai logout

Need a quick health check?

Run:

eai doctor

Need machine-readable output for automation?

Run a data-returning subcommand that advertises JSON output:

eai workspace list --format json

---

Public Checklist

Before committing a project that uses the EAI CLI:

1. .env.local is ignored.
2. No secrets or tokens are committed.
3. No private endpoint URLs are committed.
4. No workspace-specific identifiers are committed.
5. eai.config.ts contains only public-safe project metadata.
6. eai doctor runs successfully for your local setup.