@hexabot-ai/cli 3.2.2-alpha.9 → 3.2.2-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -18,20 +18,20 @@ This file is the authoritative cheat-sheet for the Hexabot CLI. It summarizes th
18
18
 
19
19
  ## Docker Compose helpers
20
20
 
21
- - **Compose resolution**: `resolveComposeFile()` ensures config paths are absolute, while `generateComposeFiles()` (`src/core/docker.ts`) builds the `-f` flag chain. It always starts with the base file, then per-service overlays (`docker-compose.<service>.yml`), optional service/mode overlays (`docker-compose.<service>.<dev|prod>.yml`), and finally the global `docker-compose.<mode>.yml` when it exists.
22
- - **Execution wrappers**: `dockerCompose()` and `dockerExec()` (same module) print highlighted commands, run them via `execSync`, and exit with code `1` on Docker failures.
21
+ - **Compose resolution**: `resolveComposeFile()` ensures config paths are absolute, `resolveComposeEnvFile()` returns an existing Docker env file for Compose `--env-file`, and `generateComposeFiles()` (`src/core/docker.ts`) builds the `-f` flag chain. It always starts with the base file, then per-service overlays (`docker-compose.<service>.yml`), optional service/mode overlays (`docker-compose.<service>.<dev|prod>.yml`), and finally the global `docker-compose.<mode>.yml` when it exists.
22
+ - **Execution wrappers**: `dockerCompose()` and `dockerExec()` (same module) print highlighted commands, run them via `execSync`, and exit with code `1` on Docker failures. Docker-mode commands pass `.env.docker` through `dockerCompose(..., { envFile })` when it exists so Compose-level interpolation uses the Docker env values.
23
23
 
24
24
  ## Subcommand Catalog
25
25
 
26
26
  | Command | Responsibilities | Options & IO | Implementation Notes |
27
27
  | --- | --- | --- | --- |
28
28
  | `check [--docker-only] [--no-docker]` | Run diagnostics for local Node version, Hexabot project detection, env files, and optionally Docker. | Flags narrow which checks run; outputs PASS/FAIL rows and sets exit code 1 if any check fails. | `src/commands/check.ts` calls `checkNodeVersion()`, `isHexabotProject()`, `loadProjectConfig()`, `listEnvStatus()`, and `checkDocker()` in sequence and prints results with chalk. |
29
- | `create <projectName>` | Scaffold a project from a GitHub template, configure package manager, bootstrap env files, install deps, and optionally start dev mode. | `--template`, `--pm`, `--no-install`, `--dev`, `--docker`, `--force`. Writes `hexabot.config.json` and new env files, installs deps (unless skipped), and can immediately run `hexabot dev`. | `src/commands/create.ts` validates the slug, downloads the latest release zip of `hexastack/hexabot-template-*` via `downloadAndExtractTemplate()`, ensures config/env files exist, installs dependencies via `installDependencies()`, and optionally calls `runDev()` for the new project. |
29
+ | `create <projectName>` | Scaffold a project from a GitHub template, configure package manager, bootstrap env files, install deps, and optionally start dev mode. | `--template`, `--pm`, `--no-install`, `--dev`, `--docker`, `--force`. Writes `hexabot.config.json`, bootstraps local and Docker env files, persists initial admin seed credentials, sets `COMPOSE_PROJECT_NAME` in `.env.docker`, installs deps (unless skipped), and can immediately run `hexabot dev`. Post-create output should clearly present `hexabot dev` as local SQLite mode and `hexabot dev --docker --services postgres` as Docker plus Postgres mode. | `src/commands/create.ts` validates the slug, downloads the latest release zip of `hexastack/hexabot-template-*` via `downloadAndExtractTemplate()`, ensures config/env files exist, installs dependencies via `installDependencies()`, and optionally calls `runDev()` for the new project. |
30
30
  | `config show` | Print the effective `hexabot.config.json` after merging defaults. | No flags; emits pretty-printed JSON. | `src/commands/config.ts` resolves the project root, asserts the workspace, and calls `loadProjectConfig()`. |
31
31
  | `config set <key> <value>` | Update nested config values via dot notation with type-aware parsing. | Supports booleans, numbers, JSON literals, comma lists (for `*Services` keys), and package-manager normalization. | Uses `parseValue()` + `buildOverride()` to construct overrides, writes via `updateProjectConfig()`, and echoes the new config. |
32
- | `dev [--docker] [--services] [-d] [--env] [--no-env-bootstrap] [--pm]` | Run the project in development mode using either the package script or Docker compose stack. | When not using Docker it runs the configured dev script (`dev` default) after optional env bootstrapping. Docker mode bootstraps the docker env file, resolves compose overlays, and runs `docker compose ... up --build [-d]`. | `src/commands/dev.ts` auto-detects the package manager, persists it into the config, handles env bootstrapping (local or docker), then either calls `runPackageScript()` or `runDockerDev()` (which uses `generateComposeFiles()` with mode `dev`). |
33
- | `start [--docker] [--services] [-d] [--build] [--env] [--env-bootstrap] [--pm]` | Production entry point mirroring `dev` but defaulting to the configured start script and prod compose overlays. | Local mode optionally bootstraps env files when `--env-bootstrap` is passed; Docker mode layers prod compose files, supports `--build`/`--detach`, and logs which services start. | `src/commands/start.ts` shares the package-manager persistence logic with `dev`. `runDockerStart()` enforces Docker availability, resolves compose overlays with mode `prod`, and shells out via `dockerCompose()`. |
34
- | ``docker up`` / ``docker down`` | Low-level Docker helpers for dev-mode compose stacks. | `up` supports `--services`, `--build`, `--detach`; `down` supports `--services` and `--volumes`. | `src/commands/docker.ts` ensures config + docker folder, resolves services (`parseServices()` with fallbacks to `config.docker.defaultServices`), bootstraps docker env files, and executes `docker compose ... up|down`. |
32
+ | `dev [--docker] [--services] [-d] [--env] [--no-env-bootstrap] [--pm]` | Run the project in development mode using either the package script or Docker compose stack. | When not using Docker it runs the configured dev script (`dev` default) after optional env bootstrapping. Docker mode bootstraps the docker env file, resolves compose overlays, and runs `docker compose --env-file .env.docker ... up --build [-d]` when the Docker env exists. | `src/commands/dev.ts` auto-detects the package manager, persists it into the config, handles env bootstrapping (local or docker), then either calls `runPackageScript()` or `runDockerDev()` (which uses `generateComposeFiles()` with mode `dev`). |
33
+ | `start [--docker] [--services] [-d] [--build] [--env] [--env-bootstrap] [--pm]` | Production entry point mirroring `dev` but defaulting to the configured start script and prod compose overlays. | Local mode optionally bootstraps env files when `--env-bootstrap` is passed; Docker mode layers prod compose files, supports `--build`/`--detach`, passes `.env.docker` to Compose when present, and logs which services start. | `src/commands/start.ts` shares the package-manager persistence logic with `dev`. `runDockerStart()` enforces Docker availability, resolves compose overlays with mode `prod`, and shells out via `dockerCompose()`. |
34
+ | ``docker up`` / ``docker down`` | Low-level Docker helpers for dev-mode compose stacks. | `up` supports `--services`, `--build`, `--detach`; `down` supports `--services` and `--volumes`. Both pass `.env.docker` to Compose when present. | `src/commands/docker.ts` ensures config + docker folder, resolves services (`parseServices()` with fallbacks to `config.docker.defaultServices`), bootstraps docker env files for `up`, and executes `docker compose ... up|down`. |
35
35
  | ``docker logs [service]`` / ``docker ps`` | Introspection helpers for the dev stack. | Logs accept `--follow`/`--since`. | Reuse `generateComposeFiles(..., 'dev')` plus targeted docker compose commands. |
36
36
  | ``docker start`` | Production-mode convenience wrapper for `hexabot start --docker`. | `--services`, `--detach`, `--build`, `--env-bootstrap`. | This subcommand simply calls `runStart({ docker: true, ... })` so behavior stays aligned with the main `start` command. |
37
37
  | `env init [--docker] [--force]` | Copy the configured `.env*` files from their `.example` counterparts. | By default bootstraps the local env; `--docker` switches to docker env paths; `--force` overwrites. | `src/commands/env.ts` calls `bootstrapEnvFile()` with the paths from the loaded config. |
@@ -46,13 +46,14 @@ This file is the authoritative cheat-sheet for the Hexabot CLI. It summarizes th
46
46
 
47
47
  ## Typical Workflow
48
48
 
49
- 1. `hexabot create my-bot --docker` — scaffold a workspace, persist the preferred package manager into `hexabot.config.json`, bootstrap both local and docker env files, and install dependencies.
49
+ 1. `hexabot create my-bot` — scaffold a workspace, persist the preferred package manager into `hexabot.config.json`, bootstrap both local and Docker env files, set the Docker Compose project name, capture initial admin credentials, and install dependencies.
50
50
  2. `cd my-bot`
51
51
  3. `hexabot check` — confirm Node/Docker availability, project structure, and env files before running heavier commands.
52
52
  4. `hexabot env init` — re-run if you need to refresh `.env` files (use `--docker` to target docker envs).
53
- 5. `hexabot dev --docker --services postgres,ollama` — spin up the dev stack with the requested services and `docker-compose.<service>.dev.yml` overlays.
54
- 6. `hexabot start` or `hexabot start --docker --services api` — run production scripts locally or via Docker.
55
- 7. `hexabot docker down --volumes` / `hexabot migrate` / `hexabot env list` as needed for lifecycle management.
53
+ 5. `hexabot dev` — run local dev with SQLite.
54
+ 6. `hexabot dev --docker --services postgres` — run dev with Docker and Postgres when needed.
55
+ 7. `hexabot start` or `hexabot start --docker --services api` — run production scripts locally or via Docker.
56
+ 8. `hexabot docker down --volumes` / `hexabot migrate` / `hexabot env list` as needed for lifecycle management.
56
57
 
57
58
  ## Extending the CLI
58
59
 
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  Hexabot CLI is the command-line entry point for creating, configuring, and operating Hexabot v3 projects. With it, you can scaffold new automation workspaces, initialize environments, start services in local or Docker modes, run database migrations, and manage the project lifecycle.
4
4
 
5
5
 
6
- Not yet familiar with [Hexabot](https://hexabot.ai/)? Hexabot v3 is an agentic AI automation platform for building and running workflows across channels with actions, bindings, memory, tools, MCP, and RAG. If you would like to learn more, please visit the [official GitHub repo](https://github.com/Hexastack/Hexabot/).
6
+ Not yet familiar with [Hexabot](https://hexabot.ai/)? Hexabot v3 is an agentic AI automation platform for building and running workflows across channels with actions, bindings, memory, tools, MCP, and RAG. If you would like to learn more, please visit the [official GitHub repo](https://github.com/hexabot-ai/Hexabot/).
7
7
 
8
8
  ## Getting Started
9
9
 
@@ -40,11 +40,11 @@ Common options:
40
40
  - `-t, --template <name>` – template repository. Use `org/repo` or shorthand `starter`.
41
41
  - `--pm <npm|pnpm|yarn|bun>` – force a package manager (auto-detected otherwise).
42
42
  - `--no-install` – skip running the package manager after scaffolding.
43
- - `--dev` – immediately run `hexabot dev` once creation is complete.
44
- - `--docker` – bootstrap the Docker env file and hint about Docker-first commands.
43
+ - `--dev` – immediately run `hexabot dev` once creation is complete (local SQLite by default).
44
+ - `--docker` – show Docker/Postgres next steps and use Docker mode when combined with `--dev`.
45
45
  - `--force` – allow scaffolding into a non-empty directory.
46
46
 
47
- The command downloads the latest template release, installs dependencies (unless `--no-install`), and bootstraps `.env` (and `.env.docker` when `--docker` is passed).
47
+ The command downloads the latest template release, installs dependencies (unless `--no-install`), and bootstraps `.env` plus `.env.docker` when their example files are present. The Docker env file is initialized with `COMPOSE_PROJECT_NAME=<project-name>` so Docker Compose uses the scaffolded project name.
48
48
 
49
49
  #### `dev`
50
50
 
@@ -54,7 +54,7 @@ Run the current project in development mode. Defaults to local (SQLite) developm
54
54
  # Local dev
55
55
  hexabot dev
56
56
 
57
- # Docker dev with Postgres profile
57
+ # Run the app with Docker and Postgres
58
58
  hexabot dev --docker --services postgres
59
59
  ```
60
60
 
@@ -87,7 +87,7 @@ Quality-of-life wrappers around `docker compose` using the project’s `docker/`
87
87
  - `hexabot docker ps`
88
88
  - `hexabot docker start [--services <list>] [--build] [-d]` – convenience alias for `hexabot start --docker`
89
89
 
90
- The CLI automatically stitches together `docker-compose.yml` + `docker-compose.<service>.yml` overlays and can copy `.env.docker.example` on first run.
90
+ The CLI automatically stitches together `docker-compose.yml` + `docker-compose.<service>.yml` overlays, can copy `.env.docker.example` on first run, and passes `.env.docker` to Docker Compose with `--env-file` when it exists.
91
91
 
92
92
  #### `start`
93
93
 
@@ -139,12 +139,10 @@ Run database migrations inside the Docker `api` container. Any extra args are fo
139
139
  hexabot dev
140
140
  ```
141
141
 
142
- 3. **Need infrastructure like Postgres or Redis? Opt in with Docker**:
142
+ 3. **Run the app with Docker and Postgres when needed**:
143
143
 
144
144
  ```sh
145
- hexabot dev --docker --services postgres,redis
146
- # or manage Docker services directly
147
- hexabot docker up --services postgres
145
+ hexabot dev --docker --services postgres
148
146
  ```
149
147
 
150
148
  That’s it—`create → cd → dev` is the happy path for a new Hexabot v3 automation project, while Docker and env helpers remain available on demand.
@@ -86,6 +86,7 @@ beforeEach(() => {
86
86
  setTTY(true);
87
87
  validateProjectName.mockReturnValue(true);
88
88
  detectPackageManager.mockReturnValue('pnpm');
89
+ bootstrapEnvFile.mockReturnValue(true);
89
90
  normalizePackageManager.mockImplementation((value) => {
90
91
  return typeof value === 'string' ? value.toLowerCase() : undefined;
91
92
  });
@@ -113,7 +114,8 @@ afterEach(() => {
113
114
  jest.restoreAllMocks();
114
115
  });
115
116
  describe('registerCreateCommand', () => {
116
- it('prompts admin credentials and persists them to local env values', async () => {
117
+ it('prompts admin credentials and persists create env values', async () => {
118
+ const logSpy = jest.spyOn(console, 'log').mockImplementation(() => { });
117
119
  input
118
120
  .mockResolvedValueOnce('Anis')
119
121
  .mockResolvedValueOnce('Bot')
@@ -136,15 +138,63 @@ describe('registerCreateCommand', () => {
136
138
  expect(templateUrl).toBe('https://github.com/marrouchi/hexabot-v3-template/archive/refs/tags/v1.0.0.zip');
137
139
  expect(projectPath.endsWith(`${path.sep}anisbot`)).toBe(true);
138
140
  expect(bootstrapEnvFile).toHaveBeenCalledWith(projectPath, '.env.example', '.env', { quiet: true });
141
+ expect(bootstrapEnvFile).toHaveBeenCalledWith(projectPath, '.env.docker.example', '.env.docker', { quiet: true });
139
142
  expect(upsertEnvVariables).toHaveBeenCalledWith(projectPath, '.env', {
140
143
  SEED_ADMIN_FIRST_NAME: 'Anis',
141
144
  SEED_ADMIN_LAST_NAME: 'Bot',
142
145
  SEED_ADMIN_EMAIL: 'anis@example.com',
143
146
  SEED_ADMIN_PASSWORD: 'Admin#123',
144
147
  });
148
+ expect(upsertEnvVariables).toHaveBeenCalledWith(projectPath, '.env.docker', {
149
+ SEED_ADMIN_FIRST_NAME: 'Anis',
150
+ SEED_ADMIN_LAST_NAME: 'Bot',
151
+ SEED_ADMIN_EMAIL: 'anis@example.com',
152
+ SEED_ADMIN_PASSWORD: 'Admin#123',
153
+ COMPOSE_PROJECT_NAME: 'anisbot',
154
+ });
145
155
  expect(exitSpy).not.toHaveBeenCalled();
146
156
  expect(input).toHaveBeenCalledTimes(3);
157
+ expect(input).toHaveBeenNthCalledWith(1, expect.objectContaining({ message: 'First name:' }));
158
+ expect(input).toHaveBeenNthCalledWith(2, expect.objectContaining({ message: 'Last name:' }));
159
+ expect(input).toHaveBeenNthCalledWith(3, expect.objectContaining({ message: 'Email:' }));
147
160
  expect(password).toHaveBeenCalledTimes(2);
161
+ expect(password).toHaveBeenNthCalledWith(1, expect.objectContaining({ message: 'Password:' }));
162
+ expect(password).toHaveBeenNthCalledWith(2, expect.objectContaining({ message: 'Confirm password:' }));
163
+ expect(bootstrapEnvFile).toHaveBeenCalledTimes(2);
164
+ expect(upsertEnvVariables).toHaveBeenCalledTimes(2);
165
+ const output = logSpy.mock.calls.flat().join('\n');
166
+ expect(output).toContain('Admin account');
167
+ expect(output).toContain('These details will be used to create the first admin user during setup.');
168
+ expect(output).toContain('You can update them later from the generated environment file before starting the app.');
169
+ expect(output).toContain('Start local dev with SQLite:');
170
+ expect(output).toContain('hexabot dev');
171
+ expect(output).toContain('Or start dev with Docker and Postgres:');
172
+ expect(output).toContain('hexabot dev --docker --services postgres');
173
+ expect(output).toContain('Optional: install Hexabot AI coding skills');
174
+ expect(output).toContain('Use these with AI coding agents to generate actions and workflows faster:');
175
+ expect(output).toContain('After starting Hexabot, you can generate an MCP token from your profile and connect your favorite AI coding agent.');
176
+ });
177
+ it('skips Docker env values when the Docker env file is unavailable', async () => {
178
+ bootstrapEnvFile.mockImplementation((_projectRoot, _exampleFile, targetFile) => targetFile === '.env');
179
+ input
180
+ .mockResolvedValueOnce('Anis')
181
+ .mockResolvedValueOnce('Bot')
182
+ .mockResolvedValueOnce('anis@example.com');
183
+ password
184
+ .mockResolvedValueOnce('Admin#123')
185
+ .mockResolvedValueOnce('Admin#123');
186
+ const program = new Command();
187
+ registerCreateCommand(program);
188
+ await program.parseAsync(['node', 'test', 'create', 'anisbot']);
189
+ const [, projectPath] = downloadAndExtractTemplate.mock.calls[0];
190
+ expect(bootstrapEnvFile).toHaveBeenCalledWith(projectPath, '.env.docker.example', '.env.docker', { quiet: true });
191
+ expect(upsertEnvVariables).toHaveBeenCalledTimes(1);
192
+ expect(upsertEnvVariables).toHaveBeenCalledWith(projectPath, '.env', {
193
+ SEED_ADMIN_FIRST_NAME: 'Anis',
194
+ SEED_ADMIN_LAST_NAME: 'Bot',
195
+ SEED_ADMIN_EMAIL: 'anis@example.com',
196
+ SEED_ADMIN_PASSWORD: 'Admin#123',
197
+ });
148
198
  });
149
199
  it('fails cleanly when create runs in a non-interactive terminal', async () => {
150
200
  setTTY(false);
@@ -8,6 +8,7 @@ const loadProjectConfig = jest.fn();
8
8
  const updateProjectConfig = jest.fn();
9
9
  const dockerCompose = jest.fn();
10
10
  const generateComposeFiles = jest.fn();
11
+ const resolveComposeEnvFile = jest.fn();
11
12
  const resolveComposeFile = jest.fn();
12
13
  const bootstrapEnvFile = jest.fn();
13
14
  const resolveEnvExample = jest.fn();
@@ -24,6 +25,7 @@ jest.unstable_mockModule('../../core/config.js', () => ({
24
25
  jest.unstable_mockModule('../../core/docker.js', () => ({
25
26
  dockerCompose,
26
27
  generateComposeFiles,
28
+ resolveComposeEnvFile,
27
29
  resolveComposeFile,
28
30
  }));
29
31
  jest.unstable_mockModule('../../core/env.js', () => ({
@@ -53,6 +55,7 @@ beforeEach(() => {
53
55
  jest.resetAllMocks();
54
56
  normalizePackageManager.mockImplementation((value) => typeof value === 'string' ? value.toLowerCase() : undefined);
55
57
  resolveComposeFile.mockReturnValue('/tmp/docker/docker-compose.yml');
58
+ resolveComposeEnvFile.mockReturnValue('/tmp/.env.docker');
56
59
  generateComposeFiles.mockReturnValue('-f docker-compose.yml');
57
60
  });
58
61
  const baseConfig = {
@@ -99,7 +102,8 @@ describe('runDev', () => {
99
102
  expect(checkDocker).toHaveBeenCalled();
100
103
  expect(ensureDockerFolder).toHaveBeenCalled();
101
104
  expect(generateComposeFiles).toHaveBeenCalledWith('/tmp/docker/docker-compose.yml', ['api', 'postgres'], 'dev');
102
- expect(dockerCompose).toHaveBeenCalledWith(expect.stringContaining('up --build -d'));
105
+ expect(resolveComposeEnvFile).toHaveBeenCalledWith(expect.any(String), baseConfig.env.docker);
106
+ expect(dockerCompose).toHaveBeenCalledWith(expect.stringContaining('up --build -d'), { envFile: '/tmp/.env.docker' });
103
107
  expect(runPackageScript).not.toHaveBeenCalled();
104
108
  });
105
109
  });
@@ -8,6 +8,7 @@ import { Command } from 'commander';
8
8
  const loadProjectConfig = jest.fn();
9
9
  const dockerCompose = jest.fn();
10
10
  const generateComposeFiles = jest.fn();
11
+ const resolveComposeEnvFile = jest.fn();
11
12
  const resolveComposeFile = jest.fn();
12
13
  const bootstrapEnvFile = jest.fn();
13
14
  const checkDocker = jest.fn();
@@ -21,6 +22,7 @@ jest.unstable_mockModule('../../core/config.js', () => ({
21
22
  jest.unstable_mockModule('../../core/docker.js', () => ({
22
23
  dockerCompose,
23
24
  generateComposeFiles,
25
+ resolveComposeEnvFile,
24
26
  resolveComposeFile,
25
27
  }));
26
28
  jest.unstable_mockModule('../../core/env.js', () => ({
@@ -49,6 +51,7 @@ beforeEach(() => {
49
51
  .split(',')
50
52
  .filter((entry) => entry));
51
53
  resolveComposeFile.mockReturnValue('/project/docker/docker-compose.yml');
54
+ resolveComposeEnvFile.mockReturnValue('/project/.env.docker');
52
55
  generateComposeFiles.mockReturnValue('-f docker-compose.yml');
53
56
  loadProjectConfig.mockReturnValue({
54
57
  docker: {
@@ -81,12 +84,13 @@ describe('registerDockerCommand', () => {
81
84
  ]);
82
85
  expect(bootstrapEnvFile).toHaveBeenCalled();
83
86
  expect(generateComposeFiles).toHaveBeenCalledWith('/project/docker/docker-compose.yml', ['api', 'postgres'], 'dev');
84
- expect(dockerCompose).toHaveBeenCalledWith(expect.stringContaining('up --build -d'));
87
+ expect(resolveComposeEnvFile).toHaveBeenCalledWith(expect.any(String), '.env.docker');
88
+ expect(dockerCompose).toHaveBeenCalledWith(expect.stringContaining('up --build -d'), { envFile: '/project/.env.docker' });
85
89
  });
86
90
  it('runs docker compose down with optional volume removal', async () => {
87
91
  const program = createProgram();
88
92
  await program.parseAsync(['node', 'test', 'docker', 'down', '--volumes']);
89
- expect(dockerCompose).toHaveBeenCalledWith(expect.stringContaining('down -v'));
93
+ expect(dockerCompose).toHaveBeenCalledWith(expect.stringContaining('down -v'), { envFile: '/project/.env.docker' });
90
94
  expect(bootstrapEnvFile).not.toHaveBeenCalled();
91
95
  });
92
96
  it('tails docker logs with filters', async () => {
@@ -101,12 +105,14 @@ describe('registerDockerCommand', () => {
101
105
  '--since',
102
106
  '1h',
103
107
  ]);
104
- expect(dockerCompose).toHaveBeenCalledWith(expect.stringContaining('logs -f --since 1h api'));
108
+ expect(dockerCompose).toHaveBeenCalledWith(expect.stringContaining('logs -f --since 1h api'), { envFile: '/project/.env.docker' });
105
109
  });
106
110
  it('lists running services with docker ps', async () => {
107
111
  const program = createProgram();
108
112
  await program.parseAsync(['node', 'test', 'docker', 'ps']);
109
- expect(dockerCompose).toHaveBeenCalledWith(expect.stringContaining('ps'));
113
+ expect(dockerCompose).toHaveBeenCalledWith(expect.stringContaining('ps'), {
114
+ envFile: '/project/.env.docker',
115
+ });
110
116
  });
111
117
  it('delegates to start command for docker start', async () => {
112
118
  const program = createProgram();
@@ -8,6 +8,7 @@ const loadProjectConfig = jest.fn();
8
8
  const updateProjectConfig = jest.fn();
9
9
  const dockerCompose = jest.fn();
10
10
  const generateComposeFiles = jest.fn();
11
+ const resolveComposeEnvFile = jest.fn();
11
12
  const resolveComposeFile = jest.fn();
12
13
  const bootstrapEnvFile = jest.fn();
13
14
  const resolveEnvExample = jest.fn();
@@ -24,6 +25,7 @@ jest.unstable_mockModule('../../core/config.js', () => ({
24
25
  jest.unstable_mockModule('../../core/docker.js', () => ({
25
26
  dockerCompose,
26
27
  generateComposeFiles,
28
+ resolveComposeEnvFile,
27
29
  resolveComposeFile,
28
30
  }));
29
31
  jest.unstable_mockModule('../../core/env.js', () => ({
@@ -89,6 +91,7 @@ describe('runStart', () => {
89
91
  loadProjectConfig.mockReturnValue(config);
90
92
  detectPackageManager.mockReturnValue('pnpm');
91
93
  resolveComposeFile.mockReturnValue('/tmp/docker/docker-compose.yml');
94
+ resolveComposeEnvFile.mockReturnValue('/tmp/.env.docker');
92
95
  generateComposeFiles.mockReturnValue('-f docker-compose.yml');
93
96
  await runStart({
94
97
  docker: true,
@@ -106,7 +109,8 @@ describe('runStart', () => {
106
109
  expect(checkDocker).toHaveBeenCalled();
107
110
  expect(ensureDockerFolder).toHaveBeenCalled();
108
111
  expect(generateComposeFiles).toHaveBeenCalledWith('/tmp/docker/docker-compose.yml', ['api', 'postgres'], 'prod');
109
- expect(dockerCompose).toHaveBeenCalledWith(expect.stringContaining('up --build -d'));
112
+ expect(resolveComposeEnvFile).toHaveBeenCalledWith(expect.any(String), config.env.docker);
113
+ expect(dockerCompose).toHaveBeenCalledWith(expect.stringContaining('up --build -d'), { envFile: '/tmp/.env.docker' });
110
114
  expect(runPackageScript).not.toHaveBeenCalled();
111
115
  });
112
116
  it('bootstraps envs for local start when requested', async () => {
@@ -21,8 +21,8 @@ export const registerCreateCommand = (program) => {
21
21
  .option('-t, --template <name>', 'Project template to use (default: starter)')
22
22
  .option('--pm <npm|pnpm|yarn|bun>', 'Preferred package manager')
23
23
  .option('--no-install', 'Skip installing dependencies')
24
- .option('--dev', 'Run hexabot dev after creation')
25
- .option('--docker', 'Bootstrap Docker env files during creation')
24
+ .option('--dev', 'Run hexabot dev after creation (local SQLite by default)')
25
+ .option('--docker', 'Show Docker/Postgres next steps and use Docker mode with --dev')
26
26
  .option('--force', 'Allow scaffolding into a non-empty directory')
27
27
  .action(async (projectName, options) => {
28
28
  await createProject(projectName, options);
@@ -49,19 +49,9 @@ const createProject = async (projectName, options) => {
49
49
  };
50
50
  ensureProjectConfig(projectPath, configOverrides);
51
51
  const config = loadProjectConfig(projectPath);
52
- bootstrapEnvFile(projectPath, config.env.localExample, config.env.local, {
53
- quiet: true,
54
- });
55
- if (options.docker) {
56
- bootstrapEnvFile(projectPath, config.env.dockerExample, config.env.docker, { quiet: true });
57
- }
52
+ const dockerEnvBootstrapped = bootstrapCreateEnvFiles(projectPath, config);
58
53
  const adminCredentials = await promptSeedAdminCredentials();
59
- upsertEnvVariables(projectPath, config.env.local, {
60
- SEED_ADMIN_FIRST_NAME: adminCredentials.firstName,
61
- SEED_ADMIN_LAST_NAME: adminCredentials.lastName,
62
- SEED_ADMIN_EMAIL: adminCredentials.email,
63
- SEED_ADMIN_PASSWORD: adminCredentials.password,
64
- });
54
+ persistAdminSeedCredentials(projectPath, config, adminCredentials, dockerEnvBootstrapped, projectName);
65
55
  if (options.noInstall) {
66
56
  console.log(chalk.yellow('Skipping dependency installation (--no-install).'));
67
57
  }
@@ -117,6 +107,31 @@ const fetchLatestReleaseTag = async (templateRepo) => {
117
107
  }
118
108
  return data.tag_name;
119
109
  };
110
+ const bootstrapCreateEnvFiles = (projectPath, config) => {
111
+ bootstrapEnvFile(projectPath, config.env.localExample, config.env.local, {
112
+ quiet: true,
113
+ });
114
+ return bootstrapEnvFile(projectPath, config.env.dockerExample, config.env.docker, { quiet: true });
115
+ };
116
+ const buildAdminSeedVariables = (credentials) => {
117
+ return {
118
+ SEED_ADMIN_FIRST_NAME: credentials.firstName,
119
+ SEED_ADMIN_LAST_NAME: credentials.lastName,
120
+ SEED_ADMIN_EMAIL: credentials.email,
121
+ SEED_ADMIN_PASSWORD: credentials.password,
122
+ };
123
+ };
124
+ const persistAdminSeedCredentials = (projectPath, config, credentials, dockerEnvBootstrapped, projectName) => {
125
+ const seedVariables = buildAdminSeedVariables(credentials);
126
+ upsertEnvVariables(projectPath, config.env.local, seedVariables);
127
+ if (dockerEnvBootstrapped ||
128
+ fs.existsSync(path.join(projectPath, config.env.docker))) {
129
+ upsertEnvVariables(projectPath, config.env.docker, {
130
+ ...seedVariables,
131
+ COMPOSE_PROJECT_NAME: projectName,
132
+ });
133
+ }
134
+ };
120
135
  const requireValue = (label) => {
121
136
  return (value) => {
122
137
  if (!value.trim()) {
@@ -155,28 +170,29 @@ const assertInteractiveTerminal = () => {
155
170
  const promptSeedAdminCredentials = async () => {
156
171
  assertInteractiveTerminal();
157
172
  console.log('\n');
158
- console.log(chalk.bold('Admin account (initial credentials)'));
159
- console.log(chalk.gray('These details are used to seed the first admin user. You can change them later in your env file.'));
173
+ console.log(chalk.bold('Admin account'));
174
+ console.log(chalk.gray('These details will be used to create the first admin user during setup.'));
175
+ console.log(chalk.gray('You can update them later from the generated environment file before starting the app.'));
160
176
  console.log('\n');
161
177
  const firstName = (await input({
162
- message: 'First name (e.g. Jhon)',
178
+ message: 'First name:',
163
179
  validate: requireValue('First name'),
164
180
  })).trim();
165
181
  const lastName = (await input({
166
- message: 'Last name (e.g. Doe)',
182
+ message: 'Last name:',
167
183
  validate: requireValue('Last name'),
168
184
  })).trim();
169
185
  const email = (await input({
170
- message: 'Email (e.g. admin@company.com)',
186
+ message: 'Email:',
171
187
  validate: validateEmail,
172
188
  })).trim();
173
189
  const adminPassword = await password({
174
- message: 'Password (min 8 chars)',
190
+ message: 'Password:',
175
191
  mask: '*',
176
192
  validate: validateAdminPassword,
177
193
  });
178
194
  await password({
179
- message: 'Confirm password',
195
+ message: 'Confirm password:',
180
196
  mask: '*',
181
197
  validate: (value) => {
182
198
  if (value !== adminPassword) {
@@ -200,15 +216,25 @@ const logSuccessMessage = (projectName, options) => {
200
216
  console.log(chalk.gray(`1. Navigate to the project folder:`));
201
217
  console.log(chalk.yellow(` cd ${projectName}`));
202
218
  if (options.docker) {
203
- console.log(chalk.gray(`2. Run dev mode with Docker (or omit --docker for local sqlite):`));
204
- console.log(chalk.yellow(` hexabot dev --docker`));
219
+ console.log(chalk.gray(`2. Start dev with Docker and Postgres:`));
220
+ console.log(chalk.yellow(` hexabot dev --docker --services postgres`));
221
+ console.log(chalk.gray(`3. Or start local dev with SQLite:`));
222
+ console.log(chalk.yellow(` hexabot dev`));
205
223
  }
206
224
  else {
207
- console.log(chalk.gray(`2. Start local dev server (SQLite by default):`));
225
+ console.log(chalk.gray(`2. Start local dev with SQLite:`));
208
226
  console.log(chalk.yellow(` hexabot dev`));
227
+ console.log(chalk.gray(`3. Or start dev with Docker and Postgres:`));
228
+ console.log(chalk.yellow(` hexabot dev --docker --services postgres`));
209
229
  }
210
- console.log(chalk.gray(`3. Explore docker helpers if needed:`));
211
- console.log(chalk.yellow(` hexabot docker up --services postgres`));
212
- console.log(chalk.gray(`Need env files? Run hexabot env init --docker`));
230
+ console.log(chalk.gray(`Env bootstrap completed.`));
231
+ console.log('\n');
232
+ console.log(chalk.blue('Optional: install Hexabot AI coding skills'));
233
+ console.log(chalk.gray('Use these with AI coding agents to generate actions and workflows faster:'));
234
+ console.log('\n');
235
+ console.log(chalk.yellow(' npx skills add hexabot-ai/action-creator'));
236
+ console.log(chalk.yellow(' npx skills add hexabot-ai/workflow-writer'));
237
+ console.log('\n');
238
+ console.log(chalk.gray('After starting Hexabot, you can generate an MCP token from your profile and connect your favorite AI coding agent.'));
213
239
  console.log('\n');
214
240
  };
@@ -6,7 +6,7 @@
6
6
  import * as path from 'path';
7
7
  import chalk from 'chalk';
8
8
  import { loadProjectConfig, updateProjectConfig } from '../core/config.js';
9
- import { dockerCompose, generateComposeFiles, resolveComposeFile, } from '../core/docker.js';
9
+ import { dockerCompose, generateComposeFiles, resolveComposeEnvFile, resolveComposeFile, } from '../core/docker.js';
10
10
  import { bootstrapEnvFile, resolveEnvExample } from '../core/env.js';
11
11
  import { detectPackageManager, normalizePackageManager, runPackageScript, } from '../core/package-manager.js';
12
12
  import { checkDocker } from '../core/prerequisites.js';
@@ -61,6 +61,7 @@ const runDockerDev = async (projectRoot, options, config) => {
61
61
  ? servicesInput
62
62
  : config.docker.defaultServices;
63
63
  const composeFile = resolveComposeFile(projectRoot, config.docker.composeFile);
64
+ const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
64
65
  const composeArgs = generateComposeFiles(composeFile, services, 'dev');
65
66
  const upArgs = ['up', '--build'];
66
67
  if (options.detach) {
@@ -68,5 +69,5 @@ const runDockerDev = async (projectRoot, options, config) => {
68
69
  }
69
70
  const composeCommand = `${composeArgs} ${upArgs.join(' ')}`.trim();
70
71
  console.log(chalk.blue(`Starting Docker services${services.length ? ` (${services.join(', ')})` : ''}`));
71
- dockerCompose(composeCommand);
72
+ dockerCompose(composeCommand, { envFile });
72
73
  };
@@ -5,7 +5,7 @@
5
5
  */
6
6
  import * as path from 'path';
7
7
  import { loadProjectConfig } from '../core/config.js';
8
- import { dockerCompose, generateComposeFiles, resolveComposeFile, } from '../core/docker.js';
8
+ import { dockerCompose, generateComposeFiles, resolveComposeEnvFile, resolveComposeFile, } from '../core/docker.js';
9
9
  import { bootstrapEnvFile } from '../core/env.js';
10
10
  import { checkDocker } from '../core/prerequisites.js';
11
11
  import { assertHexabotProject, ensureDockerFolder } from '../core/project.js';
@@ -66,6 +66,7 @@ const runDockerCommand = (lifecycle, options) => {
66
66
  bootstrapEnvFile(projectRoot, config.env.dockerExample, config.env.docker, {
67
67
  quiet: true,
68
68
  });
69
+ const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
69
70
  const commandArgs = ['up'];
70
71
  if (options.build) {
71
72
  commandArgs.push('--build');
@@ -73,14 +74,19 @@ const runDockerCommand = (lifecycle, options) => {
73
74
  if (options.detach) {
74
75
  commandArgs.push('-d');
75
76
  }
76
- dockerCompose(`${composeArgs} ${commandArgs.join(' ')}`.trim());
77
+ dockerCompose(`${composeArgs} ${commandArgs.join(' ')}`.trim(), {
78
+ envFile,
79
+ });
77
80
  }
78
81
  else {
82
+ const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
79
83
  const commandArgs = ['down'];
80
84
  if (options.volumes) {
81
85
  commandArgs.push('-v');
82
86
  }
83
- dockerCompose(`${composeArgs} ${commandArgs.join(' ')}`.trim());
87
+ dockerCompose(`${composeArgs} ${commandArgs.join(' ')}`.trim(), {
88
+ envFile,
89
+ });
84
90
  }
85
91
  };
86
92
  const runDockerLogs = (service, options) => {
@@ -91,6 +97,7 @@ const runDockerLogs = (service, options) => {
91
97
  ensureDockerFolder(projectRoot);
92
98
  const composeFile = resolveComposeFile(projectRoot, config.docker.composeFile);
93
99
  const composeArgs = generateComposeFiles(composeFile, config.docker.defaultServices, 'dev');
100
+ const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
94
101
  const args = ['logs'];
95
102
  if (options.follow) {
96
103
  args.push('-f');
@@ -101,7 +108,7 @@ const runDockerLogs = (service, options) => {
101
108
  if (service) {
102
109
  args.push(service);
103
110
  }
104
- dockerCompose(`${composeArgs} ${args.join(' ')}`.trim());
111
+ dockerCompose(`${composeArgs} ${args.join(' ')}`.trim(), { envFile });
105
112
  };
106
113
  const runDockerPs = () => {
107
114
  const projectRoot = path.resolve(process.cwd());
@@ -111,7 +118,8 @@ const runDockerPs = () => {
111
118
  ensureDockerFolder(projectRoot);
112
119
  const composeFile = resolveComposeFile(projectRoot, config.docker.composeFile);
113
120
  const composeArgs = generateComposeFiles(composeFile, config.docker.defaultServices, 'dev');
114
- dockerCompose(`${composeArgs} ps`);
121
+ const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
122
+ dockerCompose(`${composeArgs} ps`, { envFile });
115
123
  };
116
124
  const resolveServices = (servicesInput, config) => {
117
125
  const provided = parseServices(servicesInput || '');
@@ -6,7 +6,7 @@
6
6
  import * as path from 'path';
7
7
  import chalk from 'chalk';
8
8
  import { loadProjectConfig, updateProjectConfig } from '../core/config.js';
9
- import { dockerCompose, generateComposeFiles, resolveComposeFile, } from '../core/docker.js';
9
+ import { dockerCompose, generateComposeFiles, resolveComposeEnvFile, resolveComposeFile, } from '../core/docker.js';
10
10
  import { bootstrapEnvFile, resolveEnvExample } from '../core/env.js';
11
11
  import { detectPackageManager, normalizePackageManager, runPackageScript, } from '../core/package-manager.js';
12
12
  import { checkDocker } from '../core/prerequisites.js';
@@ -62,6 +62,7 @@ const runDockerStart = async (projectRoot, options, config) => {
62
62
  ? servicesInput
63
63
  : config.docker.defaultServices;
64
64
  const composeFile = resolveComposeFile(projectRoot, config.docker.composeFile);
65
+ const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
65
66
  const composeArgs = generateComposeFiles(composeFile, services, 'prod');
66
67
  const upArgs = ['up'];
67
68
  if (options.build) {
@@ -72,5 +73,5 @@ const runDockerStart = async (projectRoot, options, config) => {
72
73
  }
73
74
  const composeCommand = `${composeArgs} ${upArgs.join(' ')}`.trim();
74
75
  console.log(chalk.blue(`Starting Docker services in production mode${services.length ? ` (${services.join(', ')})` : ''}`));
75
- dockerCompose(composeCommand);
76
+ dockerCompose(composeCommand, { envFile });
76
77
  };
@@ -7,7 +7,7 @@ import fs from 'fs';
7
7
  import * as os from 'os';
8
8
  import * as path from 'path';
9
9
  import { jest } from '@jest/globals';
10
- import { generateComposeFiles } from '../docker.js';
10
+ import { generateComposeFiles, resolveComposeEnvFile } from '../docker.js';
11
11
  describe('generateComposeFiles', () => {
12
12
  let tempDir;
13
13
  let composeFile;
@@ -40,4 +40,10 @@ describe('generateComposeFiles', () => {
40
40
  `-f ${apiFile} ` +
41
41
  `-f ${serviceModeFile} -f ${mainModeFile}`);
42
42
  });
43
+ it('resolves a compose env file only when it exists', () => {
44
+ const envFile = path.join(tempDir, '.env.docker');
45
+ fs.writeFileSync(envFile, '');
46
+ expect(resolveComposeEnvFile(tempDir, '.env.docker')).toBe(envFile);
47
+ expect(resolveComposeEnvFile(tempDir, '.env.missing')).toBeUndefined();
48
+ });
43
49
  });
@@ -12,6 +12,10 @@ export const resolveComposeFile = (projectRoot, filePath) => {
12
12
  ? filePath
13
13
  : path.join(projectRoot, filePath);
14
14
  };
15
+ export const resolveComposeEnvFile = (projectRoot, filePath) => {
16
+ const envFile = resolveComposeFile(projectRoot, filePath);
17
+ return fs.existsSync(envFile) ? envFile : undefined;
18
+ };
15
19
  export const generateComposeFiles = (baseComposeFile, services, mode) => {
16
20
  if (!fs.existsSync(baseComposeFile)) {
17
21
  console.error(chalk.red(`Docker compose file not found at ${baseComposeFile}. Update hexabot.config.json.`));
@@ -39,9 +43,15 @@ export const generateComposeFiles = (baseComposeFile, services, mode) => {
39
43
  }
40
44
  return files.join(' ');
41
45
  };
42
- export const dockerCompose = (args) => {
46
+ const shellArg = (value) => {
47
+ return `'${value.replace(/'/g, `'\\''`)}'`;
48
+ };
49
+ export const dockerCompose = (args, options = {}) => {
43
50
  try {
44
- const cmd = `docker compose ${args}`;
51
+ const envArgs = options.envFile
52
+ ? `--env-file ${shellArg(options.envFile)} `
53
+ : '';
54
+ const cmd = `docker compose ${envArgs}${args}`;
45
55
  console.log(chalk.yellow(cmd));
46
56
  execSync(cmd, { stdio: 'inherit' });
47
57
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hexabot-ai/cli",
3
- "version": "3.2.2-alpha.9",
3
+ "version": "3.2.2-beta.0",
4
4
  "description": "Official Hexabot CLI for creating and managing AI chatbot/agent projects built with Hexabot.",
5
5
  "main": "dist/index.js",
6
6
  "type": "module",
@@ -104,6 +104,7 @@ beforeEach(() => {
104
104
 
105
105
  validateProjectName.mockReturnValue(true);
106
106
  detectPackageManager.mockReturnValue('pnpm');
107
+ bootstrapEnvFile.mockReturnValue(true);
107
108
  (normalizePackageManager as any).mockImplementation((value: unknown) => {
108
109
  return typeof value === 'string' ? value.toLowerCase() : undefined;
109
110
  });
@@ -133,7 +134,8 @@ afterEach(() => {
133
134
  });
134
135
 
135
136
  describe('registerCreateCommand', () => {
136
- it('prompts admin credentials and persists them to local env values', async () => {
137
+ it('prompts admin credentials and persists create env values', async () => {
138
+ const logSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
137
139
  (input as any)
138
140
  .mockResolvedValueOnce('Anis')
139
141
  .mockResolvedValueOnce('Bot')
@@ -166,15 +168,107 @@ describe('registerCreateCommand', () => {
166
168
  '.env',
167
169
  { quiet: true },
168
170
  );
171
+ expect(bootstrapEnvFile).toHaveBeenCalledWith(
172
+ projectPath,
173
+ '.env.docker.example',
174
+ '.env.docker',
175
+ { quiet: true },
176
+ );
169
177
  expect(upsertEnvVariables).toHaveBeenCalledWith(projectPath, '.env', {
170
178
  SEED_ADMIN_FIRST_NAME: 'Anis',
171
179
  SEED_ADMIN_LAST_NAME: 'Bot',
172
180
  SEED_ADMIN_EMAIL: 'anis@example.com',
173
181
  SEED_ADMIN_PASSWORD: 'Admin#123',
174
182
  });
183
+ expect(upsertEnvVariables).toHaveBeenCalledWith(
184
+ projectPath,
185
+ '.env.docker',
186
+ {
187
+ SEED_ADMIN_FIRST_NAME: 'Anis',
188
+ SEED_ADMIN_LAST_NAME: 'Bot',
189
+ SEED_ADMIN_EMAIL: 'anis@example.com',
190
+ SEED_ADMIN_PASSWORD: 'Admin#123',
191
+ COMPOSE_PROJECT_NAME: 'anisbot',
192
+ },
193
+ );
175
194
  expect(exitSpy).not.toHaveBeenCalled();
176
195
  expect(input).toHaveBeenCalledTimes(3);
196
+ expect(input).toHaveBeenNthCalledWith(
197
+ 1,
198
+ expect.objectContaining({ message: 'First name:' }),
199
+ );
200
+ expect(input).toHaveBeenNthCalledWith(
201
+ 2,
202
+ expect.objectContaining({ message: 'Last name:' }),
203
+ );
204
+ expect(input).toHaveBeenNthCalledWith(
205
+ 3,
206
+ expect.objectContaining({ message: 'Email:' }),
207
+ );
177
208
  expect(password).toHaveBeenCalledTimes(2);
209
+ expect(password).toHaveBeenNthCalledWith(
210
+ 1,
211
+ expect.objectContaining({ message: 'Password:' }),
212
+ );
213
+ expect(password).toHaveBeenNthCalledWith(
214
+ 2,
215
+ expect.objectContaining({ message: 'Confirm password:' }),
216
+ );
217
+ expect(bootstrapEnvFile).toHaveBeenCalledTimes(2);
218
+ expect(upsertEnvVariables).toHaveBeenCalledTimes(2);
219
+ const output = logSpy.mock.calls.flat().join('\n');
220
+ expect(output).toContain('Admin account');
221
+ expect(output).toContain(
222
+ 'These details will be used to create the first admin user during setup.',
223
+ );
224
+ expect(output).toContain(
225
+ 'You can update them later from the generated environment file before starting the app.',
226
+ );
227
+ expect(output).toContain('Start local dev with SQLite:');
228
+ expect(output).toContain('hexabot dev');
229
+ expect(output).toContain('Or start dev with Docker and Postgres:');
230
+ expect(output).toContain('hexabot dev --docker --services postgres');
231
+ expect(output).toContain('Optional: install Hexabot AI coding skills');
232
+ expect(output).toContain(
233
+ 'Use these with AI coding agents to generate actions and workflows faster:',
234
+ );
235
+ expect(output).toContain(
236
+ 'After starting Hexabot, you can generate an MCP token from your profile and connect your favorite AI coding agent.',
237
+ );
238
+ });
239
+
240
+ it('skips Docker env values when the Docker env file is unavailable', async () => {
241
+ (bootstrapEnvFile as any).mockImplementation(
242
+ (_projectRoot: string, _exampleFile: string, targetFile: string) =>
243
+ targetFile === '.env',
244
+ );
245
+ (input as any)
246
+ .mockResolvedValueOnce('Anis')
247
+ .mockResolvedValueOnce('Bot')
248
+ .mockResolvedValueOnce('anis@example.com');
249
+ (password as any)
250
+ .mockResolvedValueOnce('Admin#123')
251
+ .mockResolvedValueOnce('Admin#123');
252
+
253
+ const program = new Command();
254
+ registerCreateCommand(program);
255
+
256
+ await program.parseAsync(['node', 'test', 'create', 'anisbot']);
257
+
258
+ const [, projectPath] = (downloadAndExtractTemplate as any).mock.calls[0];
259
+ expect(bootstrapEnvFile).toHaveBeenCalledWith(
260
+ projectPath,
261
+ '.env.docker.example',
262
+ '.env.docker',
263
+ { quiet: true },
264
+ );
265
+ expect(upsertEnvVariables).toHaveBeenCalledTimes(1);
266
+ expect(upsertEnvVariables).toHaveBeenCalledWith(projectPath, '.env', {
267
+ SEED_ADMIN_FIRST_NAME: 'Anis',
268
+ SEED_ADMIN_LAST_NAME: 'Bot',
269
+ SEED_ADMIN_EMAIL: 'anis@example.com',
270
+ SEED_ADMIN_PASSWORD: 'Admin#123',
271
+ });
178
272
  });
179
273
 
180
274
  it('fails cleanly when create runs in a non-interactive terminal', async () => {
@@ -10,6 +10,7 @@ const loadProjectConfig = jest.fn();
10
10
  const updateProjectConfig = jest.fn();
11
11
  const dockerCompose = jest.fn();
12
12
  const generateComposeFiles = jest.fn();
13
+ const resolveComposeEnvFile = jest.fn();
13
14
  const resolveComposeFile = jest.fn();
14
15
  const bootstrapEnvFile = jest.fn();
15
16
  const resolveEnvExample = jest.fn();
@@ -28,6 +29,7 @@ jest.unstable_mockModule('../../core/config.js', () => ({
28
29
  jest.unstable_mockModule('../../core/docker.js', () => ({
29
30
  dockerCompose,
30
31
  generateComposeFiles,
32
+ resolveComposeEnvFile,
31
33
  resolveComposeFile,
32
34
  }));
33
35
 
@@ -67,6 +69,7 @@ beforeEach(() => {
67
69
  typeof value === 'string' ? value.toLowerCase() : undefined,
68
70
  );
69
71
  resolveComposeFile.mockReturnValue('/tmp/docker/docker-compose.yml');
72
+ resolveComposeEnvFile.mockReturnValue('/tmp/.env.docker');
70
73
  generateComposeFiles.mockReturnValue('-f docker-compose.yml');
71
74
  });
72
75
 
@@ -143,8 +146,13 @@ describe('runDev', () => {
143
146
  ['api', 'postgres'],
144
147
  'dev',
145
148
  );
149
+ expect(resolveComposeEnvFile).toHaveBeenCalledWith(
150
+ expect.any(String),
151
+ baseConfig.env.docker,
152
+ );
146
153
  expect(dockerCompose).toHaveBeenCalledWith(
147
154
  expect.stringContaining('up --build -d'),
155
+ { envFile: '/tmp/.env.docker' },
148
156
  );
149
157
  expect(runPackageScript).not.toHaveBeenCalled();
150
158
  });
@@ -10,6 +10,7 @@ import { Command } from 'commander';
10
10
  const loadProjectConfig = jest.fn();
11
11
  const dockerCompose = jest.fn();
12
12
  const generateComposeFiles = jest.fn();
13
+ const resolveComposeEnvFile = jest.fn();
13
14
  const resolveComposeFile = jest.fn();
14
15
  const bootstrapEnvFile = jest.fn();
15
16
  const checkDocker = jest.fn();
@@ -25,6 +26,7 @@ jest.unstable_mockModule('../../core/config.js', () => ({
25
26
  jest.unstable_mockModule('../../core/docker.js', () => ({
26
27
  dockerCompose,
27
28
  generateComposeFiles,
29
+ resolveComposeEnvFile,
28
30
  resolveComposeFile,
29
31
  }));
30
32
 
@@ -63,6 +65,7 @@ beforeEach(() => {
63
65
  .filter((entry) => entry),
64
66
  );
65
67
  resolveComposeFile.mockReturnValue('/project/docker/docker-compose.yml');
68
+ resolveComposeEnvFile.mockReturnValue('/project/.env.docker');
66
69
  generateComposeFiles.mockReturnValue('-f docker-compose.yml');
67
70
  loadProjectConfig.mockReturnValue({
68
71
  docker: {
@@ -103,8 +106,13 @@ describe('registerDockerCommand', () => {
103
106
  ['api', 'postgres'],
104
107
  'dev',
105
108
  );
109
+ expect(resolveComposeEnvFile).toHaveBeenCalledWith(
110
+ expect.any(String),
111
+ '.env.docker',
112
+ );
106
113
  expect(dockerCompose).toHaveBeenCalledWith(
107
114
  expect.stringContaining('up --build -d'),
115
+ { envFile: '/project/.env.docker' },
108
116
  );
109
117
  });
110
118
 
@@ -114,6 +122,7 @@ describe('registerDockerCommand', () => {
114
122
 
115
123
  expect(dockerCompose).toHaveBeenCalledWith(
116
124
  expect.stringContaining('down -v'),
125
+ { envFile: '/project/.env.docker' },
117
126
  );
118
127
  expect(bootstrapEnvFile).not.toHaveBeenCalled();
119
128
  });
@@ -133,6 +142,7 @@ describe('registerDockerCommand', () => {
133
142
 
134
143
  expect(dockerCompose).toHaveBeenCalledWith(
135
144
  expect.stringContaining('logs -f --since 1h api'),
145
+ { envFile: '/project/.env.docker' },
136
146
  );
137
147
  });
138
148
 
@@ -140,7 +150,9 @@ describe('registerDockerCommand', () => {
140
150
  const program = createProgram();
141
151
  await program.parseAsync(['node', 'test', 'docker', 'ps']);
142
152
 
143
- expect(dockerCompose).toHaveBeenCalledWith(expect.stringContaining('ps'));
153
+ expect(dockerCompose).toHaveBeenCalledWith(expect.stringContaining('ps'), {
154
+ envFile: '/project/.env.docker',
155
+ });
144
156
  });
145
157
 
146
158
  it('delegates to start command for docker start', async () => {
@@ -10,6 +10,7 @@ const loadProjectConfig = jest.fn();
10
10
  const updateProjectConfig = jest.fn();
11
11
  const dockerCompose = jest.fn();
12
12
  const generateComposeFiles = jest.fn();
13
+ const resolveComposeEnvFile = jest.fn();
13
14
  const resolveComposeFile = jest.fn();
14
15
  const bootstrapEnvFile = jest.fn();
15
16
  const resolveEnvExample = jest.fn();
@@ -28,6 +29,7 @@ jest.unstable_mockModule('../../core/config.js', () => ({
28
29
  jest.unstable_mockModule('../../core/docker.js', () => ({
29
30
  dockerCompose,
30
31
  generateComposeFiles,
32
+ resolveComposeEnvFile,
31
33
  resolveComposeFile,
32
34
  }));
33
35
 
@@ -112,6 +114,7 @@ describe('runStart', () => {
112
114
  loadProjectConfig.mockReturnValue(config);
113
115
  detectPackageManager.mockReturnValue('pnpm');
114
116
  resolveComposeFile.mockReturnValue('/tmp/docker/docker-compose.yml');
117
+ resolveComposeEnvFile.mockReturnValue('/tmp/.env.docker');
115
118
  generateComposeFiles.mockReturnValue('-f docker-compose.yml');
116
119
 
117
120
  await runStart({
@@ -139,8 +142,13 @@ describe('runStart', () => {
139
142
  ['api', 'postgres'],
140
143
  'prod',
141
144
  );
145
+ expect(resolveComposeEnvFile).toHaveBeenCalledWith(
146
+ expect.any(String),
147
+ config.env.docker,
148
+ );
142
149
  expect(dockerCompose).toHaveBeenCalledWith(
143
150
  expect.stringContaining('up --build -d'),
151
+ { envFile: '/tmp/.env.docker' },
144
152
  );
145
153
  expect(runPackageScript).not.toHaveBeenCalled();
146
154
  });
@@ -51,8 +51,11 @@ export const registerCreateCommand = (program: Command) => {
51
51
  )
52
52
  .option('--pm <npm|pnpm|yarn|bun>', 'Preferred package manager')
53
53
  .option('--no-install', 'Skip installing dependencies')
54
- .option('--dev', 'Run hexabot dev after creation')
55
- .option('--docker', 'Bootstrap Docker env files during creation')
54
+ .option('--dev', 'Run hexabot dev after creation (local SQLite by default)')
55
+ .option(
56
+ '--docker',
57
+ 'Show Docker/Postgres next steps and use Docker mode with --dev',
58
+ )
56
59
  .option('--force', 'Allow scaffolding into a non-empty directory')
57
60
  .action(async (projectName: string, options: CreateCommandOptions) => {
58
61
  await createProject(projectName, options);
@@ -92,26 +95,15 @@ const createProject = async (
92
95
 
93
96
  ensureProjectConfig(projectPath, configOverrides);
94
97
  const config = loadProjectConfig(projectPath);
95
-
96
- bootstrapEnvFile(projectPath, config.env.localExample, config.env.local, {
97
- quiet: true,
98
- });
99
- if (options.docker) {
100
- bootstrapEnvFile(
101
- projectPath,
102
- config.env.dockerExample,
103
- config.env.docker,
104
- { quiet: true },
105
- );
106
- }
107
-
98
+ const dockerEnvBootstrapped = bootstrapCreateEnvFiles(projectPath, config);
108
99
  const adminCredentials = await promptSeedAdminCredentials();
109
- upsertEnvVariables(projectPath, config.env.local, {
110
- SEED_ADMIN_FIRST_NAME: adminCredentials.firstName,
111
- SEED_ADMIN_LAST_NAME: adminCredentials.lastName,
112
- SEED_ADMIN_EMAIL: adminCredentials.email,
113
- SEED_ADMIN_PASSWORD: adminCredentials.password,
114
- });
100
+ persistAdminSeedCredentials(
101
+ projectPath,
102
+ config,
103
+ adminCredentials,
104
+ dockerEnvBootstrapped,
105
+ projectName,
106
+ );
115
107
 
116
108
  if (options.noInstall) {
117
109
  console.log(
@@ -185,6 +177,49 @@ const fetchLatestReleaseTag = async (templateRepo: string) => {
185
177
 
186
178
  return data.tag_name;
187
179
  };
180
+ const bootstrapCreateEnvFiles = (
181
+ projectPath: string,
182
+ config: ReturnType<typeof loadProjectConfig>,
183
+ ) => {
184
+ bootstrapEnvFile(projectPath, config.env.localExample, config.env.local, {
185
+ quiet: true,
186
+ });
187
+
188
+ return bootstrapEnvFile(
189
+ projectPath,
190
+ config.env.dockerExample,
191
+ config.env.docker,
192
+ { quiet: true },
193
+ );
194
+ };
195
+ const buildAdminSeedVariables = (credentials: AdminSeedCredentials) => {
196
+ return {
197
+ SEED_ADMIN_FIRST_NAME: credentials.firstName,
198
+ SEED_ADMIN_LAST_NAME: credentials.lastName,
199
+ SEED_ADMIN_EMAIL: credentials.email,
200
+ SEED_ADMIN_PASSWORD: credentials.password,
201
+ };
202
+ };
203
+ const persistAdminSeedCredentials = (
204
+ projectPath: string,
205
+ config: ReturnType<typeof loadProjectConfig>,
206
+ credentials: AdminSeedCredentials,
207
+ dockerEnvBootstrapped: boolean,
208
+ projectName: string,
209
+ ) => {
210
+ const seedVariables = buildAdminSeedVariables(credentials);
211
+ upsertEnvVariables(projectPath, config.env.local, seedVariables);
212
+
213
+ if (
214
+ dockerEnvBootstrapped ||
215
+ fs.existsSync(path.join(projectPath, config.env.docker))
216
+ ) {
217
+ upsertEnvVariables(projectPath, config.env.docker, {
218
+ ...seedVariables,
219
+ COMPOSE_PROJECT_NAME: projectName,
220
+ });
221
+ }
222
+ };
188
223
  const requireValue = (label: string) => {
189
224
  return (value: string) => {
190
225
  if (!value.trim()) {
@@ -231,39 +266,44 @@ const promptSeedAdminCredentials = async (): Promise<AdminSeedCredentials> => {
231
266
  assertInteractiveTerminal();
232
267
 
233
268
  console.log('\n');
234
- console.log(chalk.bold('Admin account (initial credentials)'));
269
+ console.log(chalk.bold('Admin account'));
270
+ console.log(
271
+ chalk.gray(
272
+ 'These details will be used to create the first admin user during setup.',
273
+ ),
274
+ );
235
275
  console.log(
236
276
  chalk.gray(
237
- 'These details are used to seed the first admin user. You can change them later in your env file.',
277
+ 'You can update them later from the generated environment file before starting the app.',
238
278
  ),
239
279
  );
240
280
  console.log('\n');
241
281
 
242
282
  const firstName = (
243
283
  await input({
244
- message: 'First name (e.g. Jhon)',
284
+ message: 'First name:',
245
285
  validate: requireValue('First name'),
246
286
  })
247
287
  ).trim();
248
288
  const lastName = (
249
289
  await input({
250
- message: 'Last name (e.g. Doe)',
290
+ message: 'Last name:',
251
291
  validate: requireValue('Last name'),
252
292
  })
253
293
  ).trim();
254
294
  const email = (
255
295
  await input({
256
- message: 'Email (e.g. admin@company.com)',
296
+ message: 'Email:',
257
297
  validate: validateEmail,
258
298
  })
259
299
  ).trim();
260
300
  const adminPassword = await password({
261
- message: 'Password (min 8 chars)',
301
+ message: 'Password:',
262
302
  mask: '*',
263
303
  validate: validateAdminPassword,
264
304
  });
265
305
  await password({
266
- message: 'Confirm password',
306
+ message: 'Confirm password:',
267
307
  mask: '*',
268
308
  validate: (value: string) => {
269
309
  if (value !== adminPassword) {
@@ -292,18 +332,32 @@ const logSuccessMessage = (
292
332
  console.log(chalk.gray(`1. Navigate to the project folder:`));
293
333
  console.log(chalk.yellow(` cd ${projectName}`));
294
334
  if (options.docker) {
295
- console.log(
296
- chalk.gray(
297
- `2. Run dev mode with Docker (or omit --docker for local sqlite):`,
298
- ),
299
- );
300
- console.log(chalk.yellow(` hexabot dev --docker`));
335
+ console.log(chalk.gray(`2. Start dev with Docker and Postgres:`));
336
+ console.log(chalk.yellow(` hexabot dev --docker --services postgres`));
337
+ console.log(chalk.gray(`3. Or start local dev with SQLite:`));
338
+ console.log(chalk.yellow(` hexabot dev`));
301
339
  } else {
302
- console.log(chalk.gray(`2. Start local dev server (SQLite by default):`));
340
+ console.log(chalk.gray(`2. Start local dev with SQLite:`));
303
341
  console.log(chalk.yellow(` hexabot dev`));
342
+ console.log(chalk.gray(`3. Or start dev with Docker and Postgres:`));
343
+ console.log(chalk.yellow(` hexabot dev --docker --services postgres`));
304
344
  }
305
- console.log(chalk.gray(`3. Explore docker helpers if needed:`));
306
- console.log(chalk.yellow(` hexabot docker up --services postgres`));
307
- console.log(chalk.gray(`Need env files? Run hexabot env init --docker`));
345
+ console.log(chalk.gray(`Env bootstrap completed.`));
346
+ console.log('\n');
347
+ console.log(chalk.blue('Optional: install Hexabot AI coding skills'));
348
+ console.log(
349
+ chalk.gray(
350
+ 'Use these with AI coding agents to generate actions and workflows faster:',
351
+ ),
352
+ );
353
+ console.log('\n');
354
+ console.log(chalk.yellow(' npx skills add hexabot-ai/action-creator'));
355
+ console.log(chalk.yellow(' npx skills add hexabot-ai/workflow-writer'));
356
+ console.log('\n');
357
+ console.log(
358
+ chalk.gray(
359
+ 'After starting Hexabot, you can generate an MCP token from your profile and connect your favorite AI coding agent.',
360
+ ),
361
+ );
308
362
  console.log('\n');
309
363
  };
@@ -13,6 +13,7 @@ import { loadProjectConfig, updateProjectConfig } from '../core/config.js';
13
13
  import {
14
14
  dockerCompose,
15
15
  generateComposeFiles,
16
+ resolveComposeEnvFile,
16
17
  resolveComposeFile,
17
18
  } from '../core/docker.js';
18
19
  import { bootstrapEnvFile, resolveEnvExample } from '../core/env.js';
@@ -106,6 +107,7 @@ const runDockerDev = async (
106
107
  projectRoot,
107
108
  config.docker.composeFile,
108
109
  );
110
+ const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
109
111
  const composeArgs = generateComposeFiles(composeFile, services, 'dev');
110
112
  const upArgs = ['up', '--build'];
111
113
  if (options.detach) {
@@ -118,5 +120,5 @@ const runDockerDev = async (
118
120
  `Starting Docker services${services.length ? ` (${services.join(', ')})` : ''}`,
119
121
  ),
120
122
  );
121
- dockerCompose(composeCommand);
123
+ dockerCompose(composeCommand, { envFile });
122
124
  };
@@ -12,6 +12,7 @@ import { loadProjectConfig } from '../core/config.js';
12
12
  import {
13
13
  dockerCompose,
14
14
  generateComposeFiles,
15
+ resolveComposeEnvFile,
15
16
  resolveComposeFile,
16
17
  } from '../core/docker.js';
17
18
  import { bootstrapEnvFile } from '../core/env.js';
@@ -115,6 +116,7 @@ const runDockerCommand = (
115
116
  bootstrapEnvFile(projectRoot, config.env.dockerExample, config.env.docker, {
116
117
  quiet: true,
117
118
  });
119
+ const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
118
120
  const commandArgs = ['up'];
119
121
  if (options.build) {
120
122
  commandArgs.push('--build');
@@ -122,13 +124,18 @@ const runDockerCommand = (
122
124
  if (options.detach) {
123
125
  commandArgs.push('-d');
124
126
  }
125
- dockerCompose(`${composeArgs} ${commandArgs.join(' ')}`.trim());
127
+ dockerCompose(`${composeArgs} ${commandArgs.join(' ')}`.trim(), {
128
+ envFile,
129
+ });
126
130
  } else {
131
+ const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
127
132
  const commandArgs = ['down'];
128
133
  if (options.volumes) {
129
134
  commandArgs.push('-v');
130
135
  }
131
- dockerCompose(`${composeArgs} ${commandArgs.join(' ')}`.trim());
136
+ dockerCompose(`${composeArgs} ${commandArgs.join(' ')}`.trim(), {
137
+ envFile,
138
+ });
132
139
  }
133
140
  };
134
141
  const runDockerLogs = (
@@ -149,6 +156,7 @@ const runDockerLogs = (
149
156
  config.docker.defaultServices,
150
157
  'dev',
151
158
  );
159
+ const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
152
160
  const args = ['logs'];
153
161
  if (options.follow) {
154
162
  args.push('-f');
@@ -160,7 +168,7 @@ const runDockerLogs = (
160
168
  args.push(service);
161
169
  }
162
170
 
163
- dockerCompose(`${composeArgs} ${args.join(' ')}`.trim());
171
+ dockerCompose(`${composeArgs} ${args.join(' ')}`.trim(), { envFile });
164
172
  };
165
173
  const runDockerPs = () => {
166
174
  const projectRoot = path.resolve(process.cwd());
@@ -177,8 +185,9 @@ const runDockerPs = () => {
177
185
  config.docker.defaultServices,
178
186
  'dev',
179
187
  );
188
+ const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
180
189
 
181
- dockerCompose(`${composeArgs} ps`);
190
+ dockerCompose(`${composeArgs} ps`, { envFile });
182
191
  };
183
192
  const resolveServices = (
184
193
  servicesInput: string | undefined,
@@ -13,6 +13,7 @@ import { loadProjectConfig, updateProjectConfig } from '../core/config.js';
13
13
  import {
14
14
  dockerCompose,
15
15
  generateComposeFiles,
16
+ resolveComposeEnvFile,
16
17
  resolveComposeFile,
17
18
  } from '../core/docker.js';
18
19
  import { bootstrapEnvFile, resolveEnvExample } from '../core/env.js';
@@ -105,6 +106,7 @@ const runDockerStart = async (
105
106
  projectRoot,
106
107
  config.docker.composeFile,
107
108
  );
109
+ const envFile = resolveComposeEnvFile(projectRoot, config.env.docker);
108
110
  const composeArgs = generateComposeFiles(composeFile, services, 'prod');
109
111
  const upArgs = ['up'];
110
112
  if (options.build) {
@@ -122,5 +124,5 @@ const runDockerStart = async (
122
124
  }`,
123
125
  ),
124
126
  );
125
- dockerCompose(composeCommand);
127
+ dockerCompose(composeCommand, { envFile });
126
128
  };
@@ -10,7 +10,7 @@ import * as path from 'path';
10
10
 
11
11
  import { jest } from '@jest/globals';
12
12
 
13
- import { generateComposeFiles } from '../docker.js';
13
+ import { generateComposeFiles, resolveComposeEnvFile } from '../docker.js';
14
14
 
15
15
  describe('generateComposeFiles', () => {
16
16
  let tempDir: string;
@@ -56,4 +56,12 @@ describe('generateComposeFiles', () => {
56
56
  `-f ${serviceModeFile} -f ${mainModeFile}`,
57
57
  );
58
58
  });
59
+
60
+ it('resolves a compose env file only when it exists', () => {
61
+ const envFile = path.join(tempDir, '.env.docker');
62
+ fs.writeFileSync(envFile, '');
63
+
64
+ expect(resolveComposeEnvFile(tempDir, '.env.docker')).toBe(envFile);
65
+ expect(resolveComposeEnvFile(tempDir, '.env.missing')).toBeUndefined();
66
+ });
59
67
  });
@@ -12,12 +12,25 @@ import chalk from 'chalk';
12
12
 
13
13
  export type ComposeMode = 'dev' | 'prod';
14
14
 
15
+ export interface DockerComposeOptions {
16
+ envFile?: string;
17
+ }
18
+
15
19
  export const resolveComposeFile = (projectRoot: string, filePath: string) => {
16
20
  return path.isAbsolute(filePath)
17
21
  ? filePath
18
22
  : path.join(projectRoot, filePath);
19
23
  };
20
24
 
25
+ export const resolveComposeEnvFile = (
26
+ projectRoot: string,
27
+ filePath: string,
28
+ ) => {
29
+ const envFile = resolveComposeFile(projectRoot, filePath);
30
+
31
+ return fs.existsSync(envFile) ? envFile : undefined;
32
+ };
33
+
21
34
  export const generateComposeFiles = (
22
35
  baseComposeFile: string,
23
36
  services: string[],
@@ -61,9 +74,19 @@ export const generateComposeFiles = (
61
74
  return files.join(' ');
62
75
  };
63
76
 
64
- export const dockerCompose = (args: string) => {
77
+ const shellArg = (value: string) => {
78
+ return `'${value.replace(/'/g, `'\\''`)}'`;
79
+ };
80
+
81
+ export const dockerCompose = (
82
+ args: string,
83
+ options: DockerComposeOptions = {},
84
+ ) => {
65
85
  try {
66
- const cmd = `docker compose ${args}`;
86
+ const envArgs = options.envFile
87
+ ? `--env-file ${shellArg(options.envFile)} `
88
+ : '';
89
+ const cmd = `docker compose ${envArgs}${args}`;
67
90
  console.log(chalk.yellow(cmd));
68
91
  execSync(cmd, { stdio: 'inherit' });
69
92
  } catch (_error) {