@hexabot-ai/cli 3.2.2-alpha.17 → 3.2.2-alpha.19

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`, bootstraps local and Docker env files, persists initial admin seed credentials, 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`. | `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,7 +46,7 @@ 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` — scaffold a workspace, persist the preferred package manager into `hexabot.config.json`, bootstrap both local and Docker env files, capture initial admin credentials, 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).
package/README.md CHANGED
@@ -44,7 +44,7 @@ Common options:
44
44
  - `--docker` – show Docker-first 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` plus `.env.docker` when their example files are present.
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
 
@@ -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
 
@@ -114,7 +114,8 @@ afterEach(() => {
114
114
  jest.restoreAllMocks();
115
115
  });
116
116
  describe('registerCreateCommand', () => {
117
- it('prompts admin credentials and persists them to local and Docker env values', async () => {
117
+ it('prompts admin credentials and persists create env values', async () => {
118
+ const logSpy = jest.spyOn(console, 'log').mockImplementation(() => { });
118
119
  input
119
120
  .mockResolvedValueOnce('Anis')
120
121
  .mockResolvedValueOnce('Bot')
@@ -149,14 +150,27 @@ describe('registerCreateCommand', () => {
149
150
  SEED_ADMIN_LAST_NAME: 'Bot',
150
151
  SEED_ADMIN_EMAIL: 'anis@example.com',
151
152
  SEED_ADMIN_PASSWORD: 'Admin#123',
153
+ COMPOSE_PROJECT_NAME: 'anisbot',
152
154
  });
153
155
  expect(exitSpy).not.toHaveBeenCalled();
154
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:' }));
155
160
  expect(password).toHaveBeenCalledTimes(2);
161
+ expect(password).toHaveBeenNthCalledWith(1, expect.objectContaining({ message: 'Password:' }));
162
+ expect(password).toHaveBeenNthCalledWith(2, expect.objectContaining({ message: 'Confirm password:' }));
156
163
  expect(bootstrapEnvFile).toHaveBeenCalledTimes(2);
157
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('Optional: install Hexabot AI coding skills');
170
+ expect(output).toContain('Use these with AI coding agents to generate actions and workflows faster:');
171
+ expect(output).toContain('After starting Hexabot, you can generate an MCP token from your profile and connect your favorite AI coding agent.');
158
172
  });
159
- it('skips Docker admin credentials when the Docker env file is unavailable', async () => {
173
+ it('skips Docker env values when the Docker env file is unavailable', async () => {
160
174
  bootstrapEnvFile.mockImplementation((_projectRoot, _exampleFile, targetFile) => targetFile === '.env');
161
175
  input
162
176
  .mockResolvedValueOnce('Anis')
@@ -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 () => {
@@ -51,7 +51,7 @@ const createProject = async (projectName, options) => {
51
51
  const config = loadProjectConfig(projectPath);
52
52
  const dockerEnvBootstrapped = bootstrapCreateEnvFiles(projectPath, config);
53
53
  const adminCredentials = await promptSeedAdminCredentials();
54
- persistAdminSeedCredentials(projectPath, config, adminCredentials, dockerEnvBootstrapped);
54
+ persistAdminSeedCredentials(projectPath, config, adminCredentials, dockerEnvBootstrapped, projectName);
55
55
  if (options.noInstall) {
56
56
  console.log(chalk.yellow('Skipping dependency installation (--no-install).'));
57
57
  }
@@ -121,12 +121,15 @@ const buildAdminSeedVariables = (credentials) => {
121
121
  SEED_ADMIN_PASSWORD: credentials.password,
122
122
  };
123
123
  };
124
- const persistAdminSeedCredentials = (projectPath, config, credentials, dockerEnvBootstrapped) => {
124
+ const persistAdminSeedCredentials = (projectPath, config, credentials, dockerEnvBootstrapped, projectName) => {
125
125
  const seedVariables = buildAdminSeedVariables(credentials);
126
126
  upsertEnvVariables(projectPath, config.env.local, seedVariables);
127
127
  if (dockerEnvBootstrapped ||
128
128
  fs.existsSync(path.join(projectPath, config.env.docker))) {
129
- upsertEnvVariables(projectPath, config.env.docker, seedVariables);
129
+ upsertEnvVariables(projectPath, config.env.docker, {
130
+ ...seedVariables,
131
+ COMPOSE_PROJECT_NAME: projectName,
132
+ });
130
133
  }
131
134
  };
132
135
  const requireValue = (label) => {
@@ -167,28 +170,29 @@ const assertInteractiveTerminal = () => {
167
170
  const promptSeedAdminCredentials = async () => {
168
171
  assertInteractiveTerminal();
169
172
  console.log('\n');
170
- console.log(chalk.bold('Admin account (initial credentials)'));
171
- 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.'));
172
176
  console.log('\n');
173
177
  const firstName = (await input({
174
- message: 'First name (e.g. Jhon)',
178
+ message: 'First name:',
175
179
  validate: requireValue('First name'),
176
180
  })).trim();
177
181
  const lastName = (await input({
178
- message: 'Last name (e.g. Doe)',
182
+ message: 'Last name:',
179
183
  validate: requireValue('Last name'),
180
184
  })).trim();
181
185
  const email = (await input({
182
- message: 'Email (e.g. admin@company.com)',
186
+ message: 'Email:',
183
187
  validate: validateEmail,
184
188
  })).trim();
185
189
  const adminPassword = await password({
186
- message: 'Password (min 8 chars)',
190
+ message: 'Password:',
187
191
  mask: '*',
188
192
  validate: validateAdminPassword,
189
193
  });
190
194
  await password({
191
- message: 'Confirm password',
195
+ message: 'Confirm password:',
192
196
  mask: '*',
193
197
  validate: (value) => {
194
198
  if (value !== adminPassword) {
@@ -223,9 +227,12 @@ const logSuccessMessage = (projectName, options) => {
223
227
  console.log(chalk.yellow(` hexabot docker up --services postgres`));
224
228
  console.log(chalk.gray(`Env bootstrap completed.`));
225
229
  console.log('\n');
226
- console.log(chalk.blue('Optional: Install Hexabot skills'));
227
- console.log(chalk.gray('You can add official skills to accelerate your workflow:'));
230
+ console.log(chalk.blue('Optional: install Hexabot AI coding skills'));
231
+ console.log(chalk.gray('Use these with AI coding agents to generate actions and workflows faster:'));
232
+ console.log('\n');
228
233
  console.log(chalk.yellow(' npx skills add hexabot-ai/action-creator'));
229
234
  console.log(chalk.yellow(' npx skills add hexabot-ai/workflow-writer'));
230
235
  console.log('\n');
236
+ console.log(chalk.gray('After starting Hexabot, you can generate an MCP token from your profile and connect your favorite AI coding agent.'));
237
+ console.log('\n');
231
238
  };
@@ -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.17",
3
+ "version": "3.2.2-alpha.19",
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",
@@ -134,7 +134,8 @@ afterEach(() => {
134
134
  });
135
135
 
136
136
  describe('registerCreateCommand', () => {
137
- it('prompts admin credentials and persists them to local and Docker env values', async () => {
137
+ it('prompts admin credentials and persists create env values', async () => {
138
+ const logSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
138
139
  (input as any)
139
140
  .mockResolvedValueOnce('Anis')
140
141
  .mockResolvedValueOnce('Bot')
@@ -187,16 +188,52 @@ describe('registerCreateCommand', () => {
187
188
  SEED_ADMIN_LAST_NAME: 'Bot',
188
189
  SEED_ADMIN_EMAIL: 'anis@example.com',
189
190
  SEED_ADMIN_PASSWORD: 'Admin#123',
191
+ COMPOSE_PROJECT_NAME: 'anisbot',
190
192
  },
191
193
  );
192
194
  expect(exitSpy).not.toHaveBeenCalled();
193
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
+ );
194
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
+ );
195
217
  expect(bootstrapEnvFile).toHaveBeenCalledTimes(2);
196
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('Optional: install Hexabot AI coding skills');
228
+ expect(output).toContain(
229
+ 'Use these with AI coding agents to generate actions and workflows faster:',
230
+ );
231
+ expect(output).toContain(
232
+ 'After starting Hexabot, you can generate an MCP token from your profile and connect your favorite AI coding agent.',
233
+ );
197
234
  });
198
235
 
199
- it('skips Docker admin credentials when the Docker env file is unavailable', async () => {
236
+ it('skips Docker env values when the Docker env file is unavailable', async () => {
200
237
  (bootstrapEnvFile as any).mockImplementation(
201
238
  (_projectRoot: string, _exampleFile: string, targetFile: string) =>
202
239
  targetFile === '.env',
@@ -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
  });
@@ -99,6 +99,7 @@ const createProject = async (
99
99
  config,
100
100
  adminCredentials,
101
101
  dockerEnvBootstrapped,
102
+ projectName,
102
103
  );
103
104
 
104
105
  if (options.noInstall) {
@@ -201,6 +202,7 @@ const persistAdminSeedCredentials = (
201
202
  config: ReturnType<typeof loadProjectConfig>,
202
203
  credentials: AdminSeedCredentials,
203
204
  dockerEnvBootstrapped: boolean,
205
+ projectName: string,
204
206
  ) => {
205
207
  const seedVariables = buildAdminSeedVariables(credentials);
206
208
  upsertEnvVariables(projectPath, config.env.local, seedVariables);
@@ -209,7 +211,10 @@ const persistAdminSeedCredentials = (
209
211
  dockerEnvBootstrapped ||
210
212
  fs.existsSync(path.join(projectPath, config.env.docker))
211
213
  ) {
212
- upsertEnvVariables(projectPath, config.env.docker, seedVariables);
214
+ upsertEnvVariables(projectPath, config.env.docker, {
215
+ ...seedVariables,
216
+ COMPOSE_PROJECT_NAME: projectName,
217
+ });
213
218
  }
214
219
  };
215
220
  const requireValue = (label: string) => {
@@ -258,39 +263,44 @@ const promptSeedAdminCredentials = async (): Promise<AdminSeedCredentials> => {
258
263
  assertInteractiveTerminal();
259
264
 
260
265
  console.log('\n');
261
- console.log(chalk.bold('Admin account (initial credentials)'));
266
+ console.log(chalk.bold('Admin account'));
262
267
  console.log(
263
268
  chalk.gray(
264
- 'These details are used to seed the first admin user. You can change them later in your env file.',
269
+ 'These details will be used to create the first admin user during setup.',
270
+ ),
271
+ );
272
+ console.log(
273
+ chalk.gray(
274
+ 'You can update them later from the generated environment file before starting the app.',
265
275
  ),
266
276
  );
267
277
  console.log('\n');
268
278
 
269
279
  const firstName = (
270
280
  await input({
271
- message: 'First name (e.g. Jhon)',
281
+ message: 'First name:',
272
282
  validate: requireValue('First name'),
273
283
  })
274
284
  ).trim();
275
285
  const lastName = (
276
286
  await input({
277
- message: 'Last name (e.g. Doe)',
287
+ message: 'Last name:',
278
288
  validate: requireValue('Last name'),
279
289
  })
280
290
  ).trim();
281
291
  const email = (
282
292
  await input({
283
- message: 'Email (e.g. admin@company.com)',
293
+ message: 'Email:',
284
294
  validate: validateEmail,
285
295
  })
286
296
  ).trim();
287
297
  const adminPassword = await password({
288
- message: 'Password (min 8 chars)',
298
+ message: 'Password:',
289
299
  mask: '*',
290
300
  validate: validateAdminPassword,
291
301
  });
292
302
  await password({
293
- message: 'Confirm password',
303
+ message: 'Confirm password:',
294
304
  mask: '*',
295
305
  validate: (value: string) => {
296
306
  if (value !== adminPassword) {
@@ -333,11 +343,20 @@ const logSuccessMessage = (
333
343
  console.log(chalk.yellow(` hexabot docker up --services postgres`));
334
344
  console.log(chalk.gray(`Env bootstrap completed.`));
335
345
  console.log('\n');
336
- console.log(chalk.blue('Optional: Install Hexabot skills'));
346
+ console.log(chalk.blue('Optional: install Hexabot AI coding skills'));
337
347
  console.log(
338
- chalk.gray('You can add official skills to accelerate your workflow:'),
348
+ chalk.gray(
349
+ 'Use these with AI coding agents to generate actions and workflows faster:',
350
+ ),
339
351
  );
352
+ console.log('\n');
340
353
  console.log(chalk.yellow(' npx skills add hexabot-ai/action-creator'));
341
354
  console.log(chalk.yellow(' npx skills add hexabot-ai/workflow-writer'));
342
355
  console.log('\n');
356
+ console.log(
357
+ chalk.gray(
358
+ 'After starting Hexabot, you can generate an MCP token from your profile and connect your favorite AI coding agent.',
359
+ ),
360
+ );
361
+ console.log('\n');
343
362
  };
@@ -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) {