gflows 0.1.8 → 0.1.10

package/README.md

@@ -77,6 +77,11 @@ Available on:
 - [npm: gflows](https://www.npmjs.com/package/gflows)
 - [JSR: @alialnaghmoush/gflows](https://jsr.io/@alialnaghmoush/gflows)
 
+If installed as a local dev dependency, run via your package runner:
+
+- Bun: `bunx gflows ...` (or `bun gflows ...` when available in your Bun setup)
+- npm: `npx gflows ...`
+
 **Global install (optional):**
 
 **npm**
@@ -110,12 +115,17 @@ You can override branch names and prefixes via [configuration](#configuration).
 
 ## Quick start
 
-**1. One-time setup** in your repo (ensure `main` exists and create `dev`):
+**1. One-time setup** — In your repo, ensure `main` exists and create `dev`:
 
 ```bash
 gflows init
-gflows init --push        # also push dev to origin
-gflows init --dry-run     # show what would be done, no writes
+```
+
+Optional: use `--push` to push `dev` to the remote, or `--dry-run` to preview. To use different branch or remote names, pass `--main`, `--dev`, and `--remote`; those values are written to `.gflows.json` for future runs.
+
+```bash
+gflows init --push                                    # create dev, then push to origin
+gflows init --main main --dev develop --remote origin # custom names, persisted to .gflows.json
 ```
 
 **2. Daily development** (feature → dev):
@@ -151,19 +161,21 @@ gflows finish hotfix --push               # merge to main, then dev; tag v1.3.1;
 
 ### Summary table
 
-| Command      | Short | Description |
-|-------------|-------|--------------|
-| `init`      | `-I`  | Ensure main exists; create dev from main. |
-| `start`     | `-S`  | Create a workflow branch (requires type + name). |
-| `finish`    | `-F`  | Merge branch into target(s), optional tag (release/hotfix), delete, push. |
-| `switch`    | `-W`  | Switch to a workflow branch (picker or name). |
-| `delete`   | `-L`  | Delete local workflow branch(es). Never main/dev. |
-| `list`     | `-l`  | List workflow branches; optional type filter and remote. |
-| `bump`     | —     | Bump or rollback package version (patch/minor/major). |
-| `completion` | —   | Print shell completion script (bash \| zsh \| fish). |
-| `status`   | `-t`  | Show current branch, type, base, merge target(s), ahead/behind. |
-| `help`     | `-h`  | Show usage and quick reference. |
-| `version`  | `-V`  | Show version. |
+
+| Command      | Short | Description                                                               |
+| ------------ | ----- | ------------------------------------------------------------------------- |
+| `init`       | `-I`  | Ensure main exists; create dev from main.                                 |
+| `start`      | `-S`  | Create a workflow branch (requires type + name).                          |
+| `finish`     | `-F`  | Merge branch into target(s), optional tag (release/hotfix), delete, push. |
+| `switch`     | `-W`  | Switch to a workflow branch (picker or name).                             |
+| `delete`     | `-L`  | Delete local workflow branch(es). Never main/dev.                         |
+| `list`       | `-l`  | List workflow branches; optional type filter and remote.                  |
+| `bump`       | —     | Bump or rollback package version (patch/minor/major).                     |
+| `completion` | —     | Print shell completion script (bash | zsh | fish).                        |
+| `status`     | `-t`  | Show current branch, type, base, merge target(s), ahead/behind.           |
+| `help`       | `-h`  | Show usage and quick reference.                                           |
+| `version`    | `-V`  | Show version.                                                             |
+
 
 **Branch types (for start/finish/list):** `feature` (`-f`), `bugfix` (`-b`), `chore` (`-c`), `release` (`-r`), `hotfix` (`-x`), `spike` (`-e`).
 
@@ -173,16 +185,19 @@ gflows finish hotfix --push               # merge to main, then dev; tag v1.3.1;
 
 Ensures the **main** branch exists (exits with error if not). Creates **dev** from main if it does not exist; does nothing if dev already exists. Does not rewrite or force-push.
 
+You can set and persist config with `**--main`**, `**--dev**`, and `**-R`/`--remote**`. Any of these flags cause init to write or update `.gflows.json` with the given values (after a successful init; skipped with `--dry-run`).
+
 **Examples:**
 
 ```bash
 gflows init
 gflows init --push              # push dev to remote after creating
+gflows init --main main --dev develop --remote origin   # create dev branch "develop", persist to .gflows.json
 gflows init -C ../other-repo    # run in another directory
 gflows init --dry-run           # log intended actions only
 ```
 
-**Flags:** `--push`, `-C`/`--path <dir>`, `--dry-run`, `-v`/`--verbose`, `-q`/`--quiet`.
+**Flags:** `--push`, `--main <name>`, `--dev <name>`, `-R`/`--remote <name>` (main/dev/remote are persisted to `.gflows.json` when provided), `-C`/`--path <dir>`, `--dry-run`, `-v`/`--verbose`, `-q`/`--quiet`.
 
 ---
 
@@ -342,14 +357,16 @@ gflows -V
 
 ## Branch types in detail
 
-| Type     | Short | Base (default)   | With `-o main` | Merge target(s)       | Tag   |
-|----------|-------|------------------|-----------------|------------------------|-------|
-| feature  | `-f`  | dev              | —               | dev                    | no    |
-| bugfix   | `-b`  | dev              | main            | dev (or main if from main) | no |
-| chore    | `-c`  | dev              | —               | dev                    | no    |
-| release  | `-r`  | dev              | —               | main, then dev         | yes   |
-| hotfix   | `-x`  | main             | —               | main, then dev         | yes   |
-| spike    | `-e`  | dev              | —               | dev                    | no    |
+
+| Type    | Short | Base (default) | With `-o main` | Merge target(s)            | Tag |
+| ------- | ----- | -------------- | -------------- | -------------------------- | --- |
+| feature | `-f`  | dev            | —              | dev                        | no  |
+| bugfix  | `-b`  | dev            | main           | dev (or main if from main) | no  |
+| chore   | `-c`  | dev            | —              | dev                        | no  |
+| release | `-r`  | dev            | —              | main, then dev             | yes |
+| hotfix  | `-x`  | main           | —              | main, then dev             | yes |
+| spike   | `-e`  | dev            | —              | dev                        | no  |
+
 
 - **feature** — New functionality; branches from dev, merges to dev.
 - **bugfix** — Bug fixes. Usually from dev → dev. Use `-o main` when fixing a bug on production (branch from main, merge to main then dev).
@@ -369,9 +386,8 @@ Configuration is **optional**. Override branch names, remote, and branch **prefi
 **Resolution order** (later overrides earlier):
 
 1. Built-in defaults (`main`, `dev`, `origin`, and default prefixes).
-2. Repo config file: **`.gflows.json`** in repo root, or **`gflows`** key in **`package.json`**.
-3. Environment: **`GFLOWS_MAIN`**, **`GFLOWS_DEV`**, **`GFLOWS_REMOTE`**.
-4. CLI (e.g. `-R`/`--remote` for push).
+2. Repo config file: `**.gflows.json`** in repo root, or `**gflows**` key in `**package.json**`.
+3. CLI (e.g. `--main`, `--dev`, `-R`/`--remote`).
 
 Only include keys you want to override; the rest stay default. Invalid or malformed config is ignored (with an optional warning when using `-v`).
 
@@ -427,21 +443,12 @@ Only include keys you want to override; the rest stay default. Invalid or malfor
 }
 ```
 
-### Environment variables
-
-```bash
-export GFLOWS_MAIN=main
-export GFLOWS_DEV=develop
-export GFLOWS_REMOTE=origin
-gflows init
-```
-
 ---
 
 ## Scripting and CI
 
 - **Non-interactive:** When stdin is **not** a TTY, gflows does **not** show pickers (e.g. for switch, delete, or finish `-B`). You must pass branch names explicitly or the command exits with a clear message (exit code 1).
-- **Skip confirmations:** Use **`-y`/`--yes`** to accept defaults (e.g. "Delete branch after finish?" → no delete unless you also passed `-D`).
+- **Skip confirmations:** Use `**-y`/`--yes`** to accept defaults (e.g. "Delete branch after finish?" → no delete unless you also passed `-D`).
 - **Exit codes:** Use them in scripts: `0` success, `1` usage/validation, `2` Git/system error.
 
 **Examples:**
@@ -471,11 +478,13 @@ gflows -C ./packages/api list
 
 ## Exit codes
 
-| Code | Meaning | Typical causes |
-|------|---------|-----------------|
-| **0** | Success | Command completed without error. |
-| **1** | Usage / validation | Missing type or name for `start`; invalid branch name or version format; wrong/missing positionals for non-TTY. |
-| **2** | Git / system | Not a Git repo; branch not found; dirty working tree (start without `--force`); merge conflict on finish; rebase/merge in progress; detached HEAD; finish on main/dev; tag already exists; push failed after merge. |
+
+| Code  | Meaning            | Typical causes                                                                                                                                                                                                      |
+| ----- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **0** | Success            | Command completed without error.                                                                                                                                                                                    |
+| **1** | Usage / validation | Missing type or name for `start`; invalid branch name or version format; wrong/missing positionals for non-TTY.                                                                                                     |
+| **2** | Git / system       | Not a Git repo; branch not found; dirty working tree (start without `--force`); merge conflict on finish; rebase/merge in progress; detached HEAD; finish on main/dev; tag already exists; push failed after merge. |
+
 
 **Validation (exit 1):** Invalid version (e.g. `start release foo`), invalid branch name (e.g. `feature/bad..name`), or missing required args in non-interactive mode.
 
@@ -485,19 +494,21 @@ gflows -C ./packages/api list
 
 ## Troubleshooting
 
-| Situation | What to do |
-|-----------|------------|
-| **"Not a Git repository"** | Run from a directory that contains `.git`, or use `-C <path>` to point to the repo root. |
-| **"Working tree has uncommitted changes"** | Commit or stash changes before `start`, or use `--force` (only when you intend to carry uncommitted work). |
-| **"Merge conflict while merging into …"** | Resolve conflicts in your working tree, then run `git add` and `git merge --continue` (or `git merge --abort` to cancel). Re-run `gflows finish` after resolving if needed. |
-| **"Tag v1.2.3 already exists"** | Use a new version for the release/hotfix, or delete/move the tag if you know what you’re doing. gflows does not overwrite tags. |
-| **"Cannot finish the long-lived branch main/dev"** | You’re on main or dev. Checkout a workflow branch first, or use `-B <branch>` to finish another branch. |
-| **"HEAD is detached"** | Checkout a branch (e.g. `git checkout dev`) before running `start` or `finish`. |
-| **"A rebase or merge is in progress"** | Run `git rebase --abort` or `git merge --abort`, or complete the operation, then retry gflows. |
-| **Picker not showing / "requires branch name"** | Without a TTY, gflows does not show interactive pickers. Pass the branch name explicitly (e.g. `-B feature/xyz` or `gflows switch feature/xyz`). |
-| **Wrong remote or branch names** | Set `GFLOWS_MAIN`, `GFLOWS_DEV`, `GFLOWS_REMOTE` or use `.gflows.json` / `package.json` "gflows" key. Use `-R` for one-off remote override. |
 
-Use **`-v`/`--verbose`** to see git commands and extra diagnostics; combine with the error message to pinpoint the cause.
+| Situation                                          | What to do                                                                                                                                                                  |
+| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **"Not a Git repository"**                         | Run from a directory that contains `.git`, or use `-C <path>` to point to the repo root.                                                                                    |
+| **"Working tree has uncommitted changes"**         | Commit or stash changes before `start`, or use `--force` (only when you intend to carry uncommitted work).                                                                  |
+| **"Merge conflict while merging into …"**          | Resolve conflicts in your working tree, then run `git add` and `git merge --continue` (or `git merge --abort` to cancel). Re-run `gflows finish` after resolving if needed. |
+| **"Tag v1.2.3 already exists"**                    | Use a new version for the release/hotfix, or delete/move the tag if you know what you’re doing. gflows does not overwrite tags.                                             |
+| **"Cannot finish the long-lived branch main/dev"** | You’re on main or dev. Checkout a workflow branch first, or use `-B <branch>` to finish another branch.                                                                     |
+| **"HEAD is detached"**                             | Checkout a branch (e.g. `git checkout dev`) before running `start` or `finish`.                                                                                             |
+| **"A rebase or merge is in progress"**             | Run `git rebase --abort` or `git merge --abort`, or complete the operation, then retry gflows.                                                                              |
+| **Picker not showing / "requires branch name"**    | Without a TTY, gflows does not show interactive pickers. Pass the branch name explicitly (e.g. `-B feature/xyz` or `gflows switch feature/xyz`).                            |
+| **Wrong remote or branch names**                   | Use `.gflows.json` or `package.json` "gflows" key, or `gflows init --main … --dev … --remote …`. Use `-R` for one-off remote override.                                      |
+
+
+Use `**-v`/`--verbose`** to see git commands and extra diagnostics; combine with the error message to pinpoint the cause.
 
 ---
 
@@ -551,22 +562,22 @@ bun run publish:all -- --force   # skip pre-publish checks (clean tree, branch m
 
 1. Ensure you’re on **main** with a clean working tree (or use `--force` when intentional).
 2. Bump version and tag in Git yourself, or use gflows bump + your own commit:
-   ```bash
+  ```bash
    gflows bump up minor --dry-run   # confirm
    gflows bump up minor
    git add package.json jsr.json && git commit -m "chore: bump to 1.4.0"
-   ```
+  ```
 3. Run the publish script:
-   ```bash
+  ```bash
    bun run publish:all -- --dry-run # verify
    bun run publish:all
-   ```
+  ```
 4. Optionally push main and tags:
-   ```bash
+  ```bash
    git push origin main --tags
-   ```
+  ```
 
-**Version sync:** The script reads `version` from **package.json** and writes it to **jsr.json** before publishing so the two registries never drift. Use **`gflows bump`** to change the version; the script does not bump for you.
+**Version sync:** The script reads `version` from **package.json** and writes it to **jsr.json** before publishing so the two registries never drift. Use `**gflows bump`** to change the version; the script does not bump for you.
 
 ### JSR score (100%)
 
@@ -574,10 +585,10 @@ To get a 100% score on [JSR](https://jsr.io/@alialnaghmoush/gflows/score):
 
 1. **Description** — Set in `jsr.json` (already added). If the score still shows 0/1, set the description in [package settings](https://jsr.io/@alialnaghmoush/gflows/settings) on JSR.
 2. **Runtime compatibility** — In [package settings](https://jsr.io/@alialnaghmoush/gflows/settings), open “Runtime compatibility” and mark at least **Bun** and **Node.js** (or others) as **Supported**.
-3. **Provenance** — The repo includes [`.github/workflows/publish.yml`](.github/workflows/publish.yml) (test, lint, then publish to npm and JSR). In JSR package settings, **link** the package to this GitHub repository. Add `NPM_TOKEN` in repo Secrets for npm. After that, pushes to `main` run CI and publish both registries; JSR records provenance.
+3. **Provenance** — The repo includes `[.github/workflows/publish.yml](.github/workflows/publish.yml)` (test, lint, then publish to npm and JSR). In JSR package settings, **link** the package to this GitHub repository. Add `NPM_TOKEN` in repo Secrets for npm. After that, pushes to `main` run CI and publish both registries; JSR records provenance.
 
 ---
 
 ## License
 
-See [LICENSE](LICENSE) in this repository.
+See [LICENSE](LICENSE) in this repository.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gflows",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "A lightweight CLI for consistent Git branching workflows (main + dev, feature/bugfix/chore/release/hotfix).",
   "license": "MIT",
   "type": "module",

package/src/cli.ts

@@ -1,3 +1,5 @@
+#!/usr/bin/env bun
+
 /**
  * CLI entrypoint for gflows. Parses argv, resolves -C/path, dispatches to commands,
  * and ensures exit codes and unhandled rejections are handled.
@@ -78,6 +80,8 @@ function buildParseArgsOptions() {
       // Common
       push: { type: "boolean" as const, short: "p" },
       noPush: { type: "boolean" as const, short: "P" },
+      main: { type: "string" as const },
+      dev: { type: "string" as const },
       remote: { type: "string" as const, short: "R" },
       from: { type: "string" as const, short: "o" },
       branch: { type: "string" as const, short: "B" },
@@ -276,6 +280,8 @@ export function parse(argv: string[] = Bun.argv.slice(2)): ParsedArgs {
     bumpType,
     push: v.push === true,
     noPush: v.noPush === true,
+    main: typeof v.main === "string" && v.main.trim() !== "" ? v.main.trim() : undefined,
+    dev: typeof v.dev === "string" && v.dev.trim() !== "" ? v.dev.trim() : undefined,
     remote: typeof v.remote === "string" ? v.remote : undefined,
     branch: typeof v.branch === "string" ? v.branch : undefined,
     yes: v.yes === true,

package/src/commands/delete.ts

@@ -50,7 +50,11 @@ export async function run(args: ParsedArgs): Promise<void> {
     if (err instanceof NotRepoError) throw err;
     throw err;
   });
-  const config = resolveConfig(root);
+  const config = resolveConfig(root, {
+    main: args.main,
+    dev: args.dev,
+    remote: args.remote,
+  });
   const { main, dev, prefixes } = config;
 
   const fromPositionals = (rawBranchNames ?? [])

package/src/commands/finish.ts

@@ -91,7 +91,7 @@ export async function run(args: ParsedArgs): Promise<void> {
   const repoRoot = await resolveRepoRoot(args.cwd);
   const config = resolveConfig(
     repoRoot,
-    { remote: args.remote },
+    { main: args.main, dev: args.dev, remote: args.remote },
     { verbose: args.verbose }
   );
 

package/src/commands/help.ts

@@ -33,7 +33,9 @@ Types: feature (-f), bugfix (-b), chore (-c), release (-r), hotfix (-x), spike (
 Common flags:
   -p, --push           Push after init/start/finish
   -P, --no-push        Do not push
-  -R, --remote <name>  Remote name for push
+  --main <name>        Main branch (init: persist to .gflows.json)
+  --dev <name>         Dev branch (init: persist to .gflows.json)
+  -R, --remote <name>  Remote for push (init: persist to .gflows.json)
   -o, --from <branch>  Base branch override (e.g. -o main for bugfix)
   -B, --branch <name>  Branch name (finish: branch to finish)
   -y, --yes            Skip confirmations

package/src/commands/init.ts

@@ -1,9 +1,10 @@
 /**
  * Init command: ensure main exists, create dev from main, optional push and dry-run.
+ * Can persist main, dev, and remote to .gflows.json via --main, --dev, --remote.
  * @module commands/init
  */
 
-import { resolveConfig } from "../config.js";
+import { resolveConfig, writeConfigFile } from "../config.js";
 import { BranchNotFoundError, NotRepoError } from "../errors.js";
 import {
   branchList,
@@ -18,14 +19,21 @@ import type { ParsedArgs } from "../types.js";
  * Runs the init command: ensure main exists, create dev from main if missing, optional push.
  * Pre-check: cwd (or -C) must be a git repo; main branch must exist (exit 2 otherwise).
  * Skips creating dev if it already exists. Supports --dry-run and --push.
+ * When --main, --dev, or --remote are passed, writes or updates .gflows.json with those values.
  *
- * @param args - Parsed CLI args (cwd, dryRun, push, noPush, remote, verbose, quiet).
+ * @param args - Parsed CLI args (cwd, dryRun, push, noPush, main, dev, remote, verbose, quiet).
  */
 export async function run(args: ParsedArgs): Promise<void> {
   const repoRoot = await resolveRepoRoot(args.cwd);
-  const config = resolveConfig(repoRoot, {
-    remote: args.remote,
-  }, { verbose: args.verbose });
+  const config = resolveConfig(
+    repoRoot,
+    {
+      main: args.main,
+      dev: args.dev,
+      remote: args.remote,
+    },
+    { verbose: args.verbose }
+  );
 
   const opts = {
     dryRun: args.dryRun,
@@ -67,4 +75,16 @@ export async function run(args: ParsedArgs): Promise<void> {
       console.error(`gflows: pushed '${config.dev}' to '${config.remote}'.`);
     }
   }
+
+  const hasConfigFlags = args.main !== undefined || args.dev !== undefined || args.remote !== undefined;
+  if (!args.dryRun && hasConfigFlags) {
+    writeConfigFile(repoRoot, {
+      ...(args.main !== undefined && { main: args.main }),
+      ...(args.dev !== undefined && { dev: args.dev }),
+      ...(args.remote !== undefined && { remote: args.remote }),
+    });
+    if (!args.quiet) {
+      console.error("gflows: updated .gflows.json with provided options.");
+    }
+  }
 }

package/src/commands/list.ts

@@ -57,7 +57,11 @@ export async function run(args: ParsedArgs): Promise<void> {
     throw err;
   });
 
-  const config = resolveConfig(root, undefined, { verbose: !!verbose });
+  const config = resolveConfig(
+    root,
+    { main: args.main, dev: args.dev, remote: args.remote },
+    { verbose: !!verbose }
+  );
 
   if (includeRemote && !dryRun) {
     await fetch(root, config.remote, {

package/src/commands/start.ts

@@ -53,7 +53,7 @@ export async function run(args: ParsedArgs): Promise<void> {
   const repoRoot = await resolveRepoRoot(args.cwd);
   const config = resolveConfig(
     repoRoot,
-    { remote: args.remote },
+    { main: args.main, dev: args.dev, remote: args.remote },
     { verbose: args.verbose }
   );
 

package/src/commands/status.ts

@@ -74,7 +74,11 @@ export async function run(args: ParsedArgs): Promise<void> {
     throw err;
   });
 
-  const config = resolveConfig(root, undefined, { verbose: !!verbose });
+  const config = resolveConfig(
+    root,
+    { main: args.main, dev: args.dev, remote: args.remote },
+    { verbose: !!verbose }
+  );
   const current = await getCurrentBranch(root, {
     dryRun: !!dryRun,
     verbose: !!verbose,

package/src/commands/switch.ts

@@ -49,7 +49,11 @@ export async function run(args: ParsedArgs): Promise<void> {
     if (err instanceof NotRepoError) throw err;
     throw err;
   });
-  const config = resolveConfig(root);
+  const config = resolveConfig(root, {
+    main: args.main,
+    dev: args.dev,
+    remote: args.remote,
+  });
 
   const branchName = (branch?.trim() || name?.trim() || "").trim() || undefined;
 

package/src/config.ts

@@ -1,10 +1,10 @@
 /**
- * Config resolution for gflows: defaults → repo config file → env → CLI overrides.
+ * Config resolution for gflows: defaults → repo config file → CLI overrides.
  * Exposes resolved main, dev, remote, and branch type prefixes for use by commands.
  * @module config
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type {
   BranchPrefixes,
@@ -24,11 +24,7 @@ const CONFIG_FILE = ".gflows.json";
 const PACKAGE_JSON = "package.json";
 const GFLOWS_KEY = "gflows";
 
-const ENV_MAIN = "GFLOWS_MAIN";
-const ENV_DEV = "GFLOWS_DEV";
-const ENV_REMOTE = "GFLOWS_REMOTE";
-
-/** CLI overrides for main, dev, and remote (e.g. from -R/--remote or future flags). */
+/** CLI overrides for main, dev, and remote (e.g. --main, --dev, -R/--remote). */
 export interface ConfigCliOverrides {
   main?: string;
   dev?: string;
@@ -121,26 +117,6 @@ function normalizeConfigFile(data: unknown): GflowsConfigFile | null {
   return out;
 }
 
-/**
- * Returns config overrides from environment (GFLOWS_MAIN, GFLOWS_DEV, GFLOWS_REMOTE).
- */
-export function getEnvConfigOverrides(): ConfigCliOverrides {
-  const overrides: ConfigCliOverrides = {};
-  const main = process.env[ENV_MAIN];
-  if (typeof main === "string" && main.trim() !== "") {
-    overrides.main = main.trim();
-  }
-  const dev = process.env[ENV_DEV];
-  if (typeof dev === "string" && dev.trim() !== "") {
-    overrides.dev = dev.trim();
-  }
-  const remote = process.env[ENV_REMOTE];
-  if (typeof remote === "string" && remote.trim() !== "") {
-    overrides.remote = remote.trim();
-  }
-  return overrides;
-}
-
 /**
  * Merges prefix overrides into a full Required<BranchPrefixes> (defaults + overrides).
  */
@@ -157,11 +133,11 @@ function mergePrefixes(overrides?: BranchPrefixes): Required<BranchPrefixes> {
 }
 
 /**
- * Resolves full config for the given directory: defaults → file → env → CLI.
+ * Resolves full config for the given directory: defaults → file → CLI.
  * Uses dir as the repo root for locating .gflows.json and package.json.
  *
  * @param dir - Directory to read config from (e.g. cwd or resolved -C path).
- * @param cliOverrides - Optional overrides from CLI (e.g. --remote).
+ * @param cliOverrides - Optional overrides from CLI (e.g. --main, --dev, --remote).
  * @param options - Optional { verbose } to warn when config file is missing or invalid.
  * @returns Resolved config with main, dev, remote, and full prefixes.
  */
@@ -189,11 +165,6 @@ export function resolveConfig(
     if (file.prefixes !== undefined) prefixes = mergePrefixes(file.prefixes);
   }
 
-  const envOverrides = getEnvConfigOverrides();
-  if (envOverrides.main !== undefined) main = envOverrides.main;
-  if (envOverrides.dev !== undefined) dev = envOverrides.dev;
-  if (envOverrides.remote !== undefined) remote = envOverrides.remote;
-
   if (cliOverrides?.main !== undefined) main = cliOverrides.main;
   if (cliOverrides?.dev !== undefined) dev = cliOverrides.dev;
   if (cliOverrides?.remote !== undefined) remote = cliOverrides.remote;
@@ -201,6 +172,55 @@ export function resolveConfig(
   return { main, dev, remote, prefixes };
 }
 
+/**
+ * Writes or updates .gflows.json in dir with the given partial config.
+ * Merges with existing .gflows.json if present; only provided keys are updated.
+ * Skips keys with empty string values.
+ *
+ * @param dir - Repo root directory.
+ * @param partial - Keys to set (main, dev, remote, prefixes); omitted keys are left unchanged.
+ */
+export function writeConfigFile(
+  dir: string,
+  partial: Partial<GflowsConfigFile>
+): void {
+  const path = join(dir, CONFIG_FILE);
+  let existing: GflowsConfigFile = {};
+  if (existsSync(path)) {
+    try {
+      const raw = readFileSync(path, "utf-8");
+      const data = JSON.parse(raw) as unknown;
+      const normalized = normalizeConfigFile(data);
+      if (normalized) existing = normalized;
+    } catch {
+      // overwrite invalid file
+    }
+  }
+  const merged: GflowsConfigFile = { ...existing };
+  if (typeof partial.main === "string" && partial.main.trim() !== "") {
+    merged.main = partial.main.trim();
+  }
+  if (typeof partial.dev === "string" && partial.dev.trim() !== "") {
+    merged.dev = partial.dev.trim();
+  }
+  if (typeof partial.remote === "string" && partial.remote.trim() !== "") {
+    merged.remote = partial.remote.trim();
+  }
+  if (partial.prefixes !== undefined && partial.prefixes !== null && typeof partial.prefixes === "object" && !Array.isArray(partial.prefixes)) {
+    const prefs = partial.prefixes as Record<string, unknown>;
+    const prefixes: BranchPrefixes = { ...(merged.prefixes ?? {}) };
+    const keys: (keyof BranchPrefixes)[] = ["feature", "bugfix", "chore", "release", "hotfix", "spike"];
+    for (const k of keys) {
+      const v = prefs[k];
+      if (typeof v === "string" && v.trim() !== "") {
+        prefixes[k] = v.trim();
+      }
+    }
+    merged.prefixes = prefixes;
+  }
+  writeFileSync(path, JSON.stringify(merged, null, 2) + "\n", "utf-8");
+}
+
 /**
  * Returns the branch name prefix for a given branch type from resolved config.
  */

package/src/index.ts

@@ -22,9 +22,9 @@ export { BRANCH_TYPE_SHORTS } from "./types.js";
 export {
   readConfigFile,
   resolveConfig,
+  writeConfigFile,
   getPrefixForType,
   getBranchTypeMeta,
-  getEnvConfigOverrides,
 } from "./config.js";
 export type {
   ConfigCliOverrides,

package/src/types.ts

@@ -101,6 +101,10 @@ export interface ParsedArgs {
   // Common flags
   push: boolean;
   noPush: boolean;
+  /** Main branch override (e.g. from --main; init persists to .gflows.json). */
+  main: string | undefined;
+  /** Dev branch override (e.g. from --dev; init persists to .gflows.json). */
+  dev: string | undefined;
   remote: string | undefined;
   branch: string | undefined;
   yes: boolean;