pi-forge 1.1.6 → 1.2.0

package/README.md

@@ -19,20 +19,30 @@ Open <http://localhost:3000> and pick a workspace folder.
 
 ## Configuration
 
-All knobs are environment variables. Sensible defaults — set only what
-you need.
+Every knob is settable as a `--flag` on the `pi-forge` command OR as
+an environment variable. **Flags win when both are set.** Run
+`pi-forge --help` for the full grouped list.
 
-| Variable | Default | Purpose |
-|---|---|---|
-| `PORT` | `3000` | HTTP listen port |
-| `WORKSPACE_PATH` | `~/.pi-forge/workspace` | Where project code lives |
-| `PI_CONFIG_DIR` | `~/.pi/agent` | Pi SDK config (auth, models, settings) |
-| `FORGE_DATA_DIR` | `~/.pi-forge` | pi-forge state (project list) |
-| `UI_PASSWORD` | (unset) | Enables browser login if set |
-| `API_KEY` | (unset) | Enables `Authorization: Bearer` for programmatic use |
+```bash
+pi-forge --port 4000 --workspace-path ~/Code
+pi-forge --api-key @/run/secrets/api-key --no-expose-docs
+```
+
+The most common knobs:
+
+| Flag | Env var | Default | Purpose |
+|---|---|---|---|
+| `--port` | `PORT` | `3000` | HTTP listen port |
+| `--workspace-path` | `WORKSPACE_PATH` | `~/.pi-forge/workspace` | Where project code lives |
+| `--pi-config-dir` | `PI_CONFIG_DIR` | `~/.pi/agent` | Pi SDK config (auth, models, settings) |
+| `--forge-data-dir` | `FORGE_DATA_DIR` | `~/.pi-forge` | pi-forge state (project list) |
+| `--ui-password` | `UI_PASSWORD` | (unset) | Enables browser login if set |
+| `--api-key` | `API_KEY` | (unset) | Enables `Authorization: Bearer` for programmatic use |
 
-If both `UI_PASSWORD` and `API_KEY` are unset, auth is disabled. For
-production, set at minimum `API_KEY`.
+`--ui-password`, `--api-key`, and `--jwt-secret` accept `@<path>` to
+read the value from a file (avoids shell history leakage). If both
+`--ui-password` and `--api-key` are unset, auth is disabled — for
+production, set at minimum `--api-key`.
 
 ## Programmatic API
 
@@ -42,7 +52,7 @@ for the full surface and example curl flows.
 
 ## Versioning
 
-This package version (`1.1.6`) tracks the [GitHub release](https://github.com/Devin-Marks/pi-forge/releases)
+This package version (`1.2.0`) tracks the [GitHub release](https://github.com/Devin-Marks/pi-forge/releases)
 of the same name. Docker images and the npm package are published in
 lockstep on each `v*` tag.
 

package/bin/pi-forge.mjs

@@ -17,12 +17,14 @@
  * package. We override `CLIENT_DIST_PATH` here so the same server entry
  * works in all three deployment shapes without touching server code.
  *
- * Everything else (workspace path, pi config dir, forge data dir, port,
- * auth) is read from env vars and uses the server's existing defaults
- * (`~/.pi-forge/workspace`, `~/.pi/agent`, `~/.pi-forge`, port 3000) —
- * users who installed via `npm i -g pi-forge` get sensible per-user
- * paths under their home directory without any setup.
+ * Flag parsing: `cli.js` translates argv into env-var writes BEFORE
+ * `index.js` is imported, because config.js reads `process.env` at
+ * module-load time. Every server env var has an equivalent --flag —
+ * see `pi-forge --help` or `packages/server/src/cli.ts` for the
+ * complete table. Env vars still work as fallbacks for users who
+ * already have them set; flag values win when both are present.
  */
+import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -32,6 +34,33 @@ const packageRoot = resolve(here, "..");
 process.env.CLIENT_DIST_PATH ??= resolve(packageRoot, "dist", "client");
 process.env.NODE_ENV ??= "production";
 
+const cliEntry = resolve(packageRoot, "dist", "server", "cli.js");
+const { parseCliArgs, applyCliEnv, buildHelpText } = await import(pathToFileURL(cliEntry).href);
+
+const parsed = parseCliArgs(process.argv.slice(2));
+
+if (parsed.errors.length > 0) {
+  for (const err of parsed.errors) {
+    process.stderr.write(`pi-forge: ${err}\n`);
+  }
+  process.stderr.write(`pi-forge: run with --help for usage.\n`);
+  process.exit(2);
+}
+
+if (parsed.helpRequested) {
+  const pkg = JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8"));
+  process.stdout.write(buildHelpText(pkg.version));
+  process.exit(0);
+}
+
+if (parsed.versionRequested) {
+  const pkg = JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8"));
+  process.stdout.write(`pi-forge ${pkg.version}\n`);
+  process.exit(0);
+}
+
+applyCliEnv(parsed);
+
 const serverEntry = resolve(packageRoot, "dist", "server", "index.js");
 const { start } = await import(pathToFileURL(serverEntry).href);
 await start();