@hexabot-ai/cli 3.0.0-alpha.3 → 3.1.1-alpha.0

package/dist/commands/__tests__/create.test.js

@@ -0,0 +1,158 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+import fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { jest } from '@jest/globals';
+import { Command } from 'commander';
+const ensureProjectConfig = jest.fn();
+const loadProjectConfig = jest.fn();
+const bootstrapEnvFile = jest.fn();
+const upsertEnvVariables = jest.fn();
+const detectPackageManager = jest.fn();
+const installDependencies = jest.fn();
+const normalizePackageManager = jest.fn();
+const downloadAndExtractTemplate = jest.fn();
+const validateProjectName = jest.fn();
+const runDev = jest.fn();
+const input = jest.fn();
+const password = jest.fn();
+jest.unstable_mockModule('../../core/config.js', () => ({
+    ensureProjectConfig,
+    loadProjectConfig,
+}));
+jest.unstable_mockModule('../../core/env.js', () => ({
+    bootstrapEnvFile,
+    upsertEnvVariables,
+}));
+jest.unstable_mockModule('../../core/package-manager.js', () => ({
+    detectPackageManager,
+    installDependencies,
+    normalizePackageManager,
+}));
+jest.unstable_mockModule('../../services/templates.js', () => ({
+    downloadAndExtractTemplate,
+}));
+jest.unstable_mockModule('../../utils/validation.js', () => ({
+    validateProjectName,
+}));
+jest.unstable_mockModule('../dev.js', () => ({
+    runDev,
+}));
+jest.unstable_mockModule('@inquirer/prompts', () => ({
+    input,
+    password,
+}));
+let registerCreateCommand;
+const initialCwd = process.cwd();
+const initialStdinTTY = Object.getOwnPropertyDescriptor(process.stdin, 'isTTY');
+const initialStdoutTTY = Object.getOwnPropertyDescriptor(process.stdout, 'isTTY');
+let tempDir;
+let exitSpy;
+const restoreTTY = () => {
+    if (initialStdinTTY) {
+        Object.defineProperty(process.stdin, 'isTTY', initialStdinTTY);
+    }
+    else {
+        delete process.stdin.isTTY;
+    }
+    if (initialStdoutTTY) {
+        Object.defineProperty(process.stdout, 'isTTY', initialStdoutTTY);
+    }
+    else {
+        delete process.stdout.isTTY;
+    }
+};
+const setTTY = (enabled) => {
+    Object.defineProperty(process.stdin, 'isTTY', {
+        configurable: true,
+        value: enabled,
+    });
+    Object.defineProperty(process.stdout, 'isTTY', {
+        configurable: true,
+        value: enabled,
+    });
+};
+beforeAll(async () => {
+    ({ registerCreateCommand } = await import('../create.js'));
+});
+beforeEach(() => {
+    jest.resetAllMocks();
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hexabot-create-'));
+    process.chdir(tempDir);
+    setTTY(true);
+    validateProjectName.mockReturnValue(true);
+    detectPackageManager.mockReturnValue('pnpm');
+    normalizePackageManager.mockImplementation((value) => {
+        return typeof value === 'string' ? value.toLowerCase() : undefined;
+    });
+    loadProjectConfig.mockReturnValue({
+        packageManager: 'pnpm',
+        env: {
+            local: '.env',
+            localExample: '.env.example',
+            docker: '.env.docker',
+            dockerExample: '.env.docker.example',
+        },
+    });
+    globalThis.fetch = jest.fn(async () => ({
+        ok: true,
+        json: async () => ({ tag_name: 'v1.0.0' }),
+    }));
+    exitSpy = jest.spyOn(process, 'exit').mockImplementation((code) => {
+        throw new Error(`process.exit:${code ?? ''}`);
+    });
+});
+afterEach(() => {
+    process.chdir(initialCwd);
+    fs.rmSync(tempDir, { recursive: true, force: true });
+    restoreTTY();
+    jest.restoreAllMocks();
+});
+describe('registerCreateCommand', () => {
+    it('prompts admin credentials and persists them to local env values', async () => {
+        input
+            .mockResolvedValueOnce('Anis')
+            .mockResolvedValueOnce('Bot')
+            .mockResolvedValueOnce('anis@example.com');
+        password.mockResolvedValueOnce('Admin#123');
+        const program = new Command();
+        registerCreateCommand(program);
+        await program.parseAsync([
+            'node',
+            'test',
+            'create',
+            'anisbot',
+            '--template',
+            'marrouchi/hexabot-v3-template',
+        ]);
+        const [templateUrl, projectPath] = downloadAndExtractTemplate.mock
+            .calls[0];
+        expect(templateUrl).toBe('https://github.com/marrouchi/hexabot-v3-template/archive/refs/tags/v1.0.0.zip');
+        expect(projectPath.endsWith(`${path.sep}anisbot`)).toBe(true);
+        expect(bootstrapEnvFile).toHaveBeenCalledWith(projectPath, '.env.example', '.env', { quiet: true });
+        expect(upsertEnvVariables).toHaveBeenCalledWith(projectPath, '.env', {
+            SEED_ADMIN_FIRST_NAME: 'Anis',
+            SEED_ADMIN_LAST_NAME: 'Bot',
+            SEED_ADMIN_EMAIL: 'anis@example.com',
+            SEED_ADMIN_PASSWORD: 'Admin#123',
+        });
+        expect(exitSpy).not.toHaveBeenCalled();
+        expect(input).toHaveBeenCalledTimes(3);
+        expect(password).toHaveBeenCalledTimes(1);
+    });
+    it('fails cleanly when create runs in a non-interactive terminal', async () => {
+        setTTY(false);
+        const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => { });
+        const program = new Command();
+        registerCreateCommand(program);
+        await expect(program.parseAsync(['node', 'test', 'create', 'anisbot'])).rejects.toThrow('process.exit:1');
+        expect(errorSpy).toHaveBeenCalled();
+        expect(input).not.toHaveBeenCalled();
+        expect(password).not.toHaveBeenCalled();
+        expect(upsertEnvVariables).not.toHaveBeenCalled();
+    });
+});

package/dist/commands/create.js

@@ -5,9 +5,10 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { input, password } from '@inquirer/prompts';
 import chalk from 'chalk';
 import { ensureProjectConfig, loadProjectConfig } from '../core/config.js';
-import { bootstrapEnvFile } from '../core/env.js';
+import { bootstrapEnvFile, upsertEnvVariables } from '../core/env.js';
 import { detectPackageManager, installDependencies, normalizePackageManager, } from '../core/package-manager.js';
 import { downloadAndExtractTemplate } from '../services/templates.js';
 import { validateProjectName } from '../utils/validation.js';
@@ -54,6 +55,13 @@ const createProject = async (projectName, options) => {
         if (options.docker) {
             bootstrapEnvFile(projectPath, config.env.dockerExample, config.env.docker, { quiet: true });
         }
+        const adminCredentials = await promptSeedAdminCredentials();
+        upsertEnvVariables(projectPath, config.env.local, {
+            SEED_ADMIN_FIRST_NAME: adminCredentials.firstName,
+            SEED_ADMIN_LAST_NAME: adminCredentials.lastName,
+            SEED_ADMIN_EMAIL: adminCredentials.email,
+            SEED_ADMIN_PASSWORD: adminCredentials.password,
+        });
         if (options.noInstall) {
             console.log(chalk.yellow('Skipping dependency installation (--no-install).'));
         }
@@ -109,11 +117,60 @@ const fetchLatestReleaseTag = async (templateRepo) => {
     }
     return data.tag_name;
 };
+const requireValue = (label) => {
+    return (value) => {
+        if (!value.trim()) {
+            return `${label} is required.`;
+        }
+        return true;
+    };
+};
+const validateEmail = (value) => {
+    if (!value.trim()) {
+        return 'Email is required.';
+    }
+    const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    if (!emailPattern.test(value.trim())) {
+        return 'Enter a valid email address.';
+    }
+    return true;
+};
+const assertInteractiveTerminal = () => {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new Error('hexabot create requires an interactive terminal to capture admin credentials.');
+    }
+};
+const promptSeedAdminCredentials = async () => {
+    assertInteractiveTerminal();
+    const firstName = (await input({
+        message: 'Admin first name',
+        validate: requireValue('First name'),
+    })).trim();
+    const lastName = (await input({
+        message: 'Admin last name',
+        validate: requireValue('Last name'),
+    })).trim();
+    const email = (await input({
+        message: 'Admin email',
+        validate: validateEmail,
+    })).trim();
+    const adminPassword = await password({
+        message: 'Admin password',
+        mask: '*',
+        validate: requireValue('Password'),
+    });
+    return {
+        firstName,
+        lastName,
+        email,
+        password: adminPassword,
+    };
+};
 const logSuccessMessage = (projectName, options) => {
     console.log('\n');
     console.log(chalk.green(`🎉 Project ${projectName} created successfully.`));
     console.log('\n');
-    console.log(chalk.bgYellow.black(`Next steps:`));
+    console.log(chalk.bgYellow(`Next steps:`));
     console.log(chalk.gray(`1. Navigate to the project folder:`));
     console.log(chalk.yellow(`   cd ${projectName}`));
     if (options.docker) {
@@ -126,6 +183,6 @@ const logSuccessMessage = (projectName, options) => {
     }
     console.log(chalk.gray(`3. Explore docker helpers if needed:`));
     console.log(chalk.yellow(`   hexabot docker up --services postgres`));
-    console.log(chalk.gray(`Need env files? Run ${chalk.white('hexabot env init --docker')}`));
+    console.log(chalk.gray(`Need env files? Run hexabot env init --docker`));
     console.log('\n');
 };

package/dist/core/__tests__/env.test.js

@@ -7,7 +7,7 @@ import fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { jest } from '@jest/globals';
-import { bootstrapEnvFile, listEnvStatus, resolveEnvExample } from '../env.js';
+import { bootstrapEnvFile, listEnvStatus, resolveEnvExample, upsertEnvVariables, } from '../env.js';
 describe('env helpers', () => {
     let tempDir;
     beforeEach(() => {
@@ -68,4 +68,24 @@ describe('env helpers', () => {
         expect(resolveEnvExample(tempDir, envFile, defaultExample)).toBe(`${envFile}.example`);
         expect(resolveEnvExample(tempDir, '.missing', defaultExample)).toBe(defaultExample);
     });
+    it('upserts env variables without duplicating existing keys', () => {
+        fs.writeFileSync(path.join(tempDir, '.env'), [
+            'PORT=3000',
+            'SEED_ADMIN_EMAIL=old@example.com',
+            'SEED_ADMIN_EMAIL=legacy@example.com',
+        ].join('\n'));
+        upsertEnvVariables(tempDir, '.env', {
+            SEED_ADMIN_EMAIL: 'new@example.com',
+            SEED_ADMIN_PASSWORD: 'P@ss "word"',
+        });
+        const nextEnv = fs.readFileSync(path.join(tempDir, '.env'), 'utf-8');
+        const emailMatches = nextEnv.match(/^SEED_ADMIN_EMAIL=/gm) || [];
+        expect(emailMatches).toHaveLength(1);
+        expect(nextEnv).toContain('SEED_ADMIN_EMAIL=new@example.com');
+        expect(nextEnv).toContain('SEED_ADMIN_PASSWORD="P@ss \\"word\\""');
+        expect(nextEnv.endsWith('\n')).toBe(true);
+    });
+    it('throws when attempting to upsert a missing env file', () => {
+        expect(() => upsertEnvVariables(tempDir, '.missing', { KEY: 'value' })).toThrow('Env file ".missing" is missing.');
+    });
 });

package/dist/core/env.js

@@ -48,3 +48,50 @@ export const resolveEnvExample = (projectRoot, envFile, defaultExample) => {
     }
     return defaultExample;
 };
+const ENV_BARE_VALUE = /^[A-Za-z0-9._/:@-]*$/;
+const formatEnvValue = (value) => {
+    if (ENV_BARE_VALUE.test(value)) {
+        return value;
+    }
+    return `"${value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')}"`;
+};
+const escapeRegExp = (value) => {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+};
+export const upsertEnvVariables = (projectRoot, envFile, values) => {
+    const envPath = path.join(projectRoot, envFile);
+    if (!fs.existsSync(envPath)) {
+        throw new Error(`Env file "${envFile}" is missing.`);
+    }
+    const source = fs.readFileSync(envPath, 'utf-8');
+    let lines = source.length > 0 ? source.split(/\r?\n/) : [];
+    // Remove trailing blank line to avoid repetitive gaps after writes.
+    while (lines.length > 0 && lines[lines.length - 1] === '') {
+        lines.pop();
+    }
+    for (const [key, rawValue] of Object.entries(values)) {
+        const keyPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
+        const nextLine = `${key}=${formatEnvValue(rawValue)}`;
+        let updated = false;
+        const nextLines = [];
+        for (const line of lines) {
+            if (!keyPattern.test(line)) {
+                nextLines.push(line);
+                continue;
+            }
+            if (!updated) {
+                nextLines.push(nextLine);
+                updated = true;
+            }
+            // Skip duplicate declarations for the same key.
+        }
+        if (!updated) {
+            nextLines.push(nextLine);
+        }
+        lines = nextLines;
+    }
+    fs.writeFileSync(envPath, `${lines.join('\n')}\n`, 'utf-8');
+};

package/dist/index.js

@@ -7,10 +7,11 @@
 import { createCliProgram } from './cli.js';
 import { checkPrerequisites } from './core/prerequisites.js';
 import { printBanner } from './ui/banner.js';
+const cliArgs = process.argv.slice(2);
 printBanner();
 checkPrerequisites({ silent: true });
 const program = createCliProgram();
 program.parse(process.argv);
-if (!process.argv.slice(2).length) {
+if (!cliArgs.length) {
     program.outputHelp();
 }

package/eslint.config.cjs

@@ -33,7 +33,10 @@ const createConfig = ({ headerYear = '2025' } = {}) => {
     {
       ignores: ['dist', 'eslint.config.cjs', 'eslint.config-staged.cjs'],
     },
-    ...compat.extends('plugin:@typescript-eslint/recommended', 'plugin:prettier/recommended'),
+    ...compat.extends(
+      'plugin:@typescript-eslint/recommended',
+      'plugin:prettier/recommended',
+    ),
     {
       files: ['**/*.ts'],
       languageOptions: {
@@ -77,12 +80,21 @@ const createConfig = ({ headerYear = '2025' } = {}) => {
         ],
         'lines-between-class-members': ['warn', 'always'],
         'no-console': 'off',
-        'no-duplicate-imports': 2,
+        'no-duplicate-imports': 'off',
+        'import/no-duplicates': 'error',
         'object-shorthand': 1,
         'import/order': [
           'error',
           {
-            groups: ['builtin', 'external', 'unknown', 'parent', 'sibling', 'index', 'internal'],
+            groups: [
+              'builtin',
+              'external',
+              'unknown',
+              'parent',
+              'sibling',
+              'index',
+              'internal',
+            ],
             'newlines-between': 'always',
             alphabetize: {
               order: 'asc',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexabot-ai/cli",
-  "version": "3.0.0-alpha.3",
+  "version": "3.1.1-alpha.0",
   "description": "Official Hexabot CLI for creating and managing AI chatbot/agent projects built with Hexabot.",
   "main": "dist/index.js",
   "type": "module",
@@ -24,11 +24,12 @@
   },
   "keywords": [],
   "author": "Hexastack",
-  "license": "AGPL-3.0-only",
+  "license": "FCL-1.0-ALv2",
   "lint-staged": {
     "*.{ts}": "eslint --fix --config eslint.config-staged.cjs"
   },
   "dependencies": {
+    "@inquirer/prompts": "^7.10.1",
     "axios": "^1.7.7",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",

package/src/commands/__tests__/create.test.ts

@@ -0,0 +1,192 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { jest } from '@jest/globals';
+import { Command } from 'commander';
+
+const ensureProjectConfig = jest.fn();
+const loadProjectConfig = jest.fn();
+const bootstrapEnvFile = jest.fn();
+const upsertEnvVariables = jest.fn();
+const detectPackageManager = jest.fn();
+const installDependencies = jest.fn();
+const normalizePackageManager = jest.fn();
+const downloadAndExtractTemplate = jest.fn();
+const validateProjectName = jest.fn();
+const runDev = jest.fn();
+const input = jest.fn();
+const password = jest.fn();
+
+jest.unstable_mockModule('../../core/config.js', () => ({
+  ensureProjectConfig,
+  loadProjectConfig,
+}));
+
+jest.unstable_mockModule('../../core/env.js', () => ({
+  bootstrapEnvFile,
+  upsertEnvVariables,
+}));
+
+jest.unstable_mockModule('../../core/package-manager.js', () => ({
+  detectPackageManager,
+  installDependencies,
+  normalizePackageManager,
+}));
+
+jest.unstable_mockModule('../../services/templates.js', () => ({
+  downloadAndExtractTemplate,
+}));
+
+jest.unstable_mockModule('../../utils/validation.js', () => ({
+  validateProjectName,
+}));
+
+jest.unstable_mockModule('../dev.js', () => ({
+  runDev,
+}));
+
+jest.unstable_mockModule('@inquirer/prompts', () => ({
+  input,
+  password,
+}));
+
+let registerCreateCommand: (program: Command) => void;
+
+const initialCwd = process.cwd();
+const initialStdinTTY = Object.getOwnPropertyDescriptor(process.stdin, 'isTTY');
+const initialStdoutTTY = Object.getOwnPropertyDescriptor(
+  process.stdout,
+  'isTTY',
+);
+let tempDir: string;
+let exitSpy: ReturnType<typeof jest.spyOn>;
+
+const restoreTTY = () => {
+  if (initialStdinTTY) {
+    Object.defineProperty(process.stdin, 'isTTY', initialStdinTTY);
+  } else {
+    delete (process.stdin as { isTTY?: boolean }).isTTY;
+  }
+
+  if (initialStdoutTTY) {
+    Object.defineProperty(process.stdout, 'isTTY', initialStdoutTTY);
+  } else {
+    delete (process.stdout as { isTTY?: boolean }).isTTY;
+  }
+};
+const setTTY = (enabled: boolean) => {
+  Object.defineProperty(process.stdin, 'isTTY', {
+    configurable: true,
+    value: enabled,
+  });
+  Object.defineProperty(process.stdout, 'isTTY', {
+    configurable: true,
+    value: enabled,
+  });
+};
+
+beforeAll(async () => {
+  ({ registerCreateCommand } = await import('../create.js'));
+});
+
+beforeEach(() => {
+  jest.resetAllMocks();
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hexabot-create-'));
+  process.chdir(tempDir);
+  setTTY(true);
+
+  validateProjectName.mockReturnValue(true);
+  detectPackageManager.mockReturnValue('pnpm');
+  (normalizePackageManager as any).mockImplementation((value: unknown) => {
+    return typeof value === 'string' ? value.toLowerCase() : undefined;
+  });
+  loadProjectConfig.mockReturnValue({
+    packageManager: 'pnpm',
+    env: {
+      local: '.env',
+      localExample: '.env.example',
+      docker: '.env.docker',
+      dockerExample: '.env.docker.example',
+    },
+  });
+  (globalThis as any).fetch = jest.fn(async () => ({
+    ok: true,
+    json: async () => ({ tag_name: 'v1.0.0' }),
+  }));
+  exitSpy = jest.spyOn(process, 'exit').mockImplementation((code?: any) => {
+    throw new Error(`process.exit:${code ?? ''}`);
+  });
+});
+
+afterEach(() => {
+  process.chdir(initialCwd);
+  fs.rmSync(tempDir, { recursive: true, force: true });
+  restoreTTY();
+  jest.restoreAllMocks();
+});
+
+describe('registerCreateCommand', () => {
+  it('prompts admin credentials and persists them to local env values', async () => {
+    (input as any)
+      .mockResolvedValueOnce('Anis')
+      .mockResolvedValueOnce('Bot')
+      .mockResolvedValueOnce('anis@example.com');
+    (password as any).mockResolvedValueOnce('Admin#123');
+
+    const program = new Command();
+    registerCreateCommand(program);
+
+    await program.parseAsync([
+      'node',
+      'test',
+      'create',
+      'anisbot',
+      '--template',
+      'marrouchi/hexabot-v3-template',
+    ]);
+
+    const [templateUrl, projectPath] = (downloadAndExtractTemplate as any).mock
+      .calls[0];
+    expect(templateUrl).toBe(
+      'https://github.com/marrouchi/hexabot-v3-template/archive/refs/tags/v1.0.0.zip',
+    );
+    expect(projectPath.endsWith(`${path.sep}anisbot`)).toBe(true);
+    expect(bootstrapEnvFile).toHaveBeenCalledWith(
+      projectPath,
+      '.env.example',
+      '.env',
+      { quiet: true },
+    );
+    expect(upsertEnvVariables).toHaveBeenCalledWith(projectPath, '.env', {
+      SEED_ADMIN_FIRST_NAME: 'Anis',
+      SEED_ADMIN_LAST_NAME: 'Bot',
+      SEED_ADMIN_EMAIL: 'anis@example.com',
+      SEED_ADMIN_PASSWORD: 'Admin#123',
+    });
+    expect(exitSpy).not.toHaveBeenCalled();
+    expect(input).toHaveBeenCalledTimes(3);
+    expect(password).toHaveBeenCalledTimes(1);
+  });
+
+  it('fails cleanly when create runs in a non-interactive terminal', async () => {
+    setTTY(false);
+    const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    const program = new Command();
+    registerCreateCommand(program);
+
+    await expect(
+      program.parseAsync(['node', 'test', 'create', 'anisbot']),
+    ).rejects.toThrow('process.exit:1');
+    expect(errorSpy).toHaveBeenCalled();
+    expect(input).not.toHaveBeenCalled();
+    expect(password).not.toHaveBeenCalled();
+    expect(upsertEnvVariables).not.toHaveBeenCalled();
+  });
+});

package/src/commands/create.ts

@@ -7,11 +7,12 @@
 import * as fs from 'fs';
 import * as path from 'path';
 
+import { input, password } from '@inquirer/prompts';
 import chalk from 'chalk';
 import { Command } from 'commander';
 
 import { ensureProjectConfig, loadProjectConfig } from '../core/config.js';
-import { bootstrapEnvFile } from '../core/env.js';
+import { bootstrapEnvFile, upsertEnvVariables } from '../core/env.js';
 import {
   detectPackageManager,
   installDependencies,
@@ -33,6 +34,13 @@ interface CreateCommandOptions {
   force?: boolean;
 }
 
+interface AdminSeedCredentials {
+  firstName: string;
+  lastName: string;
+  email: string;
+  password: string;
+}
+
 export const registerCreateCommand = (program: Command) => {
   program
     .command('create <projectName>')
@@ -97,6 +105,14 @@ const createProject = async (
       );
     }
 
+    const adminCredentials = await promptSeedAdminCredentials();
+    upsertEnvVariables(projectPath, config.env.local, {
+      SEED_ADMIN_FIRST_NAME: adminCredentials.firstName,
+      SEED_ADMIN_LAST_NAME: adminCredentials.lastName,
+      SEED_ADMIN_EMAIL: adminCredentials.email,
+      SEED_ADMIN_PASSWORD: adminCredentials.password,
+    });
+
     if (options.noInstall) {
       console.log(
         chalk.yellow('Skipping dependency installation (--no-install).'),
@@ -169,6 +185,68 @@ const fetchLatestReleaseTag = async (templateRepo: string) => {
 
   return data.tag_name;
 };
+const requireValue = (label: string) => {
+  return (value: string) => {
+    if (!value.trim()) {
+      return `${label} is required.`;
+    }
+
+    return true;
+  };
+};
+const validateEmail = (value: string) => {
+  if (!value.trim()) {
+    return 'Email is required.';
+  }
+
+  const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  if (!emailPattern.test(value.trim())) {
+    return 'Enter a valid email address.';
+  }
+
+  return true;
+};
+const assertInteractiveTerminal = () => {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error(
+      'hexabot create requires an interactive terminal to capture admin credentials.',
+    );
+  }
+};
+const promptSeedAdminCredentials = async (): Promise<AdminSeedCredentials> => {
+  assertInteractiveTerminal();
+
+  const firstName = (
+    await input({
+      message: 'Admin first name',
+      validate: requireValue('First name'),
+    })
+  ).trim();
+  const lastName = (
+    await input({
+      message: 'Admin last name',
+      validate: requireValue('Last name'),
+    })
+  ).trim();
+  const email = (
+    await input({
+      message: 'Admin email',
+      validate: validateEmail,
+    })
+  ).trim();
+  const adminPassword = await password({
+    message: 'Admin password',
+    mask: '*',
+    validate: requireValue('Password'),
+  });
+
+  return {
+    firstName,
+    lastName,
+    email,
+    password: adminPassword,
+  };
+};
 const logSuccessMessage = (
   projectName: string,
   options: { docker?: boolean },
@@ -176,7 +254,7 @@ const logSuccessMessage = (
   console.log('\n');
   console.log(chalk.green(`🎉 Project ${projectName} created successfully.`));
   console.log('\n');
-  console.log(chalk.bgYellow.black(`Next steps:`));
+  console.log(chalk.bgYellow(`Next steps:`));
   console.log(chalk.gray(`1. Navigate to the project folder:`));
   console.log(chalk.yellow(`   cd ${projectName}`));
   if (options.docker) {
@@ -192,10 +270,6 @@ const logSuccessMessage = (
   }
   console.log(chalk.gray(`3. Explore docker helpers if needed:`));
   console.log(chalk.yellow(`   hexabot docker up --services postgres`));
-  console.log(
-    chalk.gray(
-      `Need env files? Run ${chalk.white('hexabot env init --docker')}`,
-    ),
-  );
+  console.log(chalk.gray(`Need env files? Run hexabot env init --docker`));
   console.log('\n');
 };

package/src/core/__tests__/env.test.ts

@@ -10,7 +10,12 @@ import * as path from 'path';
 
 import { jest } from '@jest/globals';
 
-import { bootstrapEnvFile, listEnvStatus, resolveEnvExample } from '../env.js';
+import {
+  bootstrapEnvFile,
+  listEnvStatus,
+  resolveEnvExample,
+  upsertEnvVariables,
+} from '../env.js';
 
 describe('env helpers', () => {
   let tempDir: string;
@@ -94,4 +99,33 @@ describe('env helpers', () => {
       defaultExample,
     );
   });
+
+  it('upserts env variables without duplicating existing keys', () => {
+    fs.writeFileSync(
+      path.join(tempDir, '.env'),
+      [
+        'PORT=3000',
+        'SEED_ADMIN_EMAIL=old@example.com',
+        'SEED_ADMIN_EMAIL=legacy@example.com',
+      ].join('\n'),
+    );
+
+    upsertEnvVariables(tempDir, '.env', {
+      SEED_ADMIN_EMAIL: 'new@example.com',
+      SEED_ADMIN_PASSWORD: 'P@ss "word"',
+    });
+
+    const nextEnv = fs.readFileSync(path.join(tempDir, '.env'), 'utf-8');
+    const emailMatches = nextEnv.match(/^SEED_ADMIN_EMAIL=/gm) || [];
+    expect(emailMatches).toHaveLength(1);
+    expect(nextEnv).toContain('SEED_ADMIN_EMAIL=new@example.com');
+    expect(nextEnv).toContain('SEED_ADMIN_PASSWORD="P@ss \\"word\\""');
+    expect(nextEnv.endsWith('\n')).toBe(true);
+  });
+
+  it('throws when attempting to upsert a missing env file', () => {
+    expect(() =>
+      upsertEnvVariables(tempDir, '.missing', { KEY: 'value' }),
+    ).toThrow('Env file ".missing" is missing.');
+  });
 });

package/src/core/env.ts

@@ -88,3 +88,65 @@ export const resolveEnvExample = (
 
   return defaultExample;
 };
+
+const ENV_BARE_VALUE = /^[A-Za-z0-9._/:@-]*$/;
+const formatEnvValue = (value: string) => {
+  if (ENV_BARE_VALUE.test(value)) {
+    return value;
+  }
+
+  return `"${value
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')}"`;
+};
+const escapeRegExp = (value: string) => {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+};
+
+export const upsertEnvVariables = (
+  projectRoot: string,
+  envFile: string,
+  values: Record<string, string>,
+) => {
+  const envPath = path.join(projectRoot, envFile);
+  if (!fs.existsSync(envPath)) {
+    throw new Error(`Env file "${envFile}" is missing.`);
+  }
+
+  const source = fs.readFileSync(envPath, 'utf-8');
+  let lines = source.length > 0 ? source.split(/\r?\n/) : [];
+
+  // Remove trailing blank line to avoid repetitive gaps after writes.
+  while (lines.length > 0 && lines[lines.length - 1] === '') {
+    lines.pop();
+  }
+
+  for (const [key, rawValue] of Object.entries(values)) {
+    const keyPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
+    const nextLine = `${key}=${formatEnvValue(rawValue)}`;
+    let updated = false;
+    const nextLines: string[] = [];
+
+    for (const line of lines) {
+      if (!keyPattern.test(line)) {
+        nextLines.push(line);
+        continue;
+      }
+
+      if (!updated) {
+        nextLines.push(nextLine);
+        updated = true;
+      }
+      // Skip duplicate declarations for the same key.
+    }
+
+    if (!updated) {
+      nextLines.push(nextLine);
+    }
+
+    lines = nextLines;
+  }
+
+  fs.writeFileSync(envPath, `${lines.join('\n')}\n`, 'utf-8');
+};

package/src/index.ts

@@ -9,6 +9,8 @@ import { createCliProgram } from './cli.js';
 import { checkPrerequisites } from './core/prerequisites.js';
 import { printBanner } from './ui/banner.js';
 
+const cliArgs = process.argv.slice(2);
+
 printBanner();
 checkPrerequisites({ silent: true });
 
@@ -16,6 +18,6 @@ const program = createCliProgram();
 
 program.parse(process.argv);
 
-if (!process.argv.slice(2).length) {
+if (!cliArgs.length) {
   program.outputHelp();
 }