@devflow-one/cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DevFlow One
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# devflow — CLI for the local action gateway
+
+Trigger DevFlow repo actions (branch, PR/MR, pipeline, reviewers) from the
+terminal, so shell scripts and CI-style automations can drive the same actions
+the extension panel exposes.
+
+It is a **thin HTTP client of the local gateway** the desktop app runs
+(`desktop/src/gateway/server.js`). It reads the same auto-generated token file,
+routes by Jira project key (or issue key), and prints the gateway's result. No
+provider API logic lives here — the owning browser profile executes the action.
+
+## How it works
+
+- Each command maps to one gateway action; global flags (`--issue` / `--project`
+  / `--profile` / `--repo`) supply routing, the command supplies its own args.
+- The gateway routes the action to the connected browser profile that owns the
+  project key, waits for the profile's result, and returns it.
+- Discovery: `list-actions` and `list-profiles` read straight from the live
+  gateway registry (advertised actions; connected profiles + owned keys).
+- Failures come back as structured errors (`NO_PROFILE`, `AMBIGUOUS_PROFILE`,
+  `TIMEOUT`, `DESTRUCTIVE_BLOCKED`, or an unreachable daemon), printed with their
+  code (`--json` for the machine-readable envelope).
+
+## Prerequisites
+
+- The **DevFlow desktop app must be running** — it hosts the gateway and writes
+  the token. v1 also needs the browser extension connected so a profile owns
+  project keys.
+- Node **>= 20**.
+
+## Install / run
+
+Published to npm as `@devflow-one/cli` — no clone, no build:
+
+```sh
+npm i -g @devflow-one/cli      # exposes `devflow` on your PATH
+devflow --help
+```
+
+Or run it without installing:
+
+```sh
+npx -y @devflow-one/cli --help
+```
+
+From a clone of the monorepo (contributors), the CLI is dependency-free and runs
+straight from the repo:
+
+```sh
+node cli/bin/devflow.js --help
+cd cli && npm link             # or link it onto your PATH as `devflow`
+```
+
+## Token & port (zero-config)
+
+The CLI discovers the gateway automatically — no setup — by reading the token
+file the desktop daemon writes on first run, under its userData dir:
+
+| Platform | Token path                                                     |
+| -------- | -------------------------------------------------------------- |
+| macOS    | `~/Library/Application Support/devflow/gateway-token`          |
+| Linux    | `~/.config/devflow/gateway-token`                              |
+| Windows  | `%APPDATA%\devflow\gateway-token`                              |
+
+The file is written owner-only (`0600`). Override for CI / non-standard installs:
+
+| Env var                 | Purpose                                             |
+| ----------------------- | --------------------------------------------------- |
+| `DEVFLOW_GATEWAY_TOKEN` | Provide the token directly (skips the file lookup). |
+| `DEVFLOW_GATEWAY_PORT`  | Gateway port (default `8787`).                      |
+
+## Usage
+
+```sh
+# discovery
+devflow list-actions
+devflow list-profiles                       # connected profiles + owned keys
+
+# routed by project key
+devflow branch create feat/x --project ABC
+devflow mr create "Title" feat/x --body "desc" --project ABC
+
+# routed by issue key (project key = prefix before the last '-')
+devflow mr find ABC-123 --issue ABC-123
+devflow pipeline status 42 deadbeef --issue ABC-9
+
+# commit a managed worktree with the project's commit-message template
+devflow commit template /wt/ABC-123 --values '{"summary":"fix login"}' --project ABC
+devflow commit template /wt/ABC-123 --no-push --project ABC   # commit locally, skip push
+
+# assembled fix-review-comments prompt (read-only; runs no AI, makes no writes)
+devflow mr fix-prompt 42 --issue ABC-123
+
+# notify the project's configured Slack channel(s)
+devflow slack notify "Review fixes ready on {pr}" --values '{"pr":"#42"}' --project ABC
+
+# force a specific profile when a key is ambiguous
+devflow mr ready 12 --profile prof-1
+```
+
+### Destructive actions
+
+`branch delete` and `mr close` are destructive. They are **refused unless you
+confirm** with `--force` (or `--yes`); the gateway enforces the same gate
+server-side, so the confirmation can't be bypassed:
+
+```sh
+devflow branch delete old --project ABC            # refused
+devflow branch delete old --project ABC --force    # executes
+```
+
+## Verify
+
+```sh
+npm test      # unit: arg parsing, command resolution, routing, destructive gate
+```
+
+## Releasing
+
+Publishing this package to npm is a manual, dry-run-first process — see
+[`RELEASING.md`](../RELEASING.md) at the repo root.

package/bin/devflow.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// `devflow` entry point. Delegates to the testable run() and maps its return to
+// a process exit code. Unexpected (non-tagged) errors surface with a stack.
+
+import { run } from "../src/cli.js";
+
+run(process.argv.slice(2))
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((err) => {
+    console.error(`error: ${err?.stack ?? err}`);
+    process.exitCode = 1;
+  });

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@devflow-one/cli",
+  "version": "0.1.1",
+  "description": "Terminal CLI wrapping the local DevFlow gateway so shell scripts can trigger repo actions.",
+  "keywords": [
+    "devflow",
+    "jira",
+    "cli",
+    "git",
+    "gitlab",
+    "github",
+    "merge-request",
+    "pull-request",
+    "automation"
+  ],
+  "homepage": "https://devflow-one.com",
+  "bugs": {
+    "url": "https://gitlab.com/devflow.one/monorepo/-/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/devflow.one/monorepo.git",
+    "directory": "cli"
+  },
+  "license": "MIT",
+  "author": "DevFlow One",
+  "type": "module",
+  "bin": {
+    "devflow": "bin/devflow.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "!src/tests",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test \"src/tests/**/*.test.js\""
+  },
+  "devDependencies": {
+    "release-it": "^20.0.1"
+  }
+}

package/src/args.js

@@ -0,0 +1,59 @@
+// Minimal, dependency-free argv parser. Splits argv into positionals and flags.
+// Supports `--flag value`, `--flag=value`, and boolean `--flag` (when the next
+// token is another flag or absent). `--` ends flag parsing; the rest are
+// positionals.
+
+/** Boolean flags never consume the following token. */
+const BOOLEAN_FLAGS = new Set(["json", "all", "help", "force", "yes", "no-push"]);
+
+/**
+ * @param {string[]} argv the args after the node/script path
+ * @returns {{ positionals: string[], flags: Record<string, string | boolean> }}
+ */
+export function parseArgs(argv) {
+  const positionals = [];
+  const flags = {};
+  let onlyPositionals = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+
+    if (onlyPositionals || !token.startsWith("--")) {
+      positionals.push(token);
+
+      continue;
+    }
+
+    if (token === "--") {
+      onlyPositionals = true;
+
+      continue;
+    }
+
+    const body = token.slice(2);
+    const eq = body.indexOf("=");
+
+    if (eq !== -1) {
+      flags[body.slice(0, eq)] = body.slice(eq + 1);
+
+      continue;
+    }
+
+    if (BOOLEAN_FLAGS.has(body)) {
+      flags[body] = true;
+
+      continue;
+    }
+
+    const next = argv[i + 1];
+
+    if (next === undefined || next.startsWith("--")) {
+      flags[body] = true;
+    } else {
+      flags[body] = next;
+      i++;
+    }
+  }
+
+  return { positionals, flags };
+}

package/src/cli.js

@@ -0,0 +1,190 @@
+// CLI orchestrator: parse argv → resolve command → build the routed payload →
+// call the gateway → print the result (or an actionable error). Kept free of
+// process.exit so it's unit-testable; `run()` returns an exit code.
+
+import { parseArgs } from "./args.js";
+import { resolveConfig, ConfigError } from "./config.js";
+import { gatewayRequest, GatewayError } from "./client.js";
+import { resolveCommand, listCommands, UsageError } from "./commands.js";
+
+const USAGE = `devflow — trigger DevFlow repo actions via the local gateway
+
+Usage:
+  devflow <command> [args] [--issue KEY | --project KEY] [--profile ID] [--json]
+
+Commands:
+${listCommands()
+  .map((c) => `  ${c}`)
+  .join("\n")}
+
+Routing flags (one of --issue / --project required for action commands):
+  --issue ABC-123     Route by Jira issue key (project key = prefix before last '-').
+  --project ABC       Route by project key directly.
+  --profile <id>      Force a specific Chrome profile (disambiguates ambiguity).
+  --repo <id|url>     Select a repo when the project owns several.
+
+Destructive actions (branch delete, mr close):
+  --force, --yes      Confirm a destructive action; required or it is refused.
+
+Output:
+  --json              Print machine-readable JSON (envelope) for scripts.
+
+Environment:
+  DEVFLOW_GATEWAY_PORT   Gateway port (default 8787).
+  DEVFLOW_GATEWAY_TOKEN  Override the auto-read token file.`;
+
+/** Attach the routing fields from global flags to an action request body. */
+function buildRoutingBody(flags) {
+  const body = {};
+
+  if (flags.issue) body.issueId = String(flags.issue);
+  if (flags.project) body.projectKey = String(flags.project);
+  if (flags.profile) body.profile = String(flags.profile);
+
+  return body;
+}
+
+/**
+ * The project key a payload should carry (from --project, or derived from
+ * --issue). Uppercased to match how Jira keys are stored in the extension config
+ * and the gateway routing rule (`issueKeyToProjectKey`).
+ */
+function payloadProjectKey(flags) {
+  if (flags.project) return String(flags.project).toUpperCase();
+
+  if (flags.issue) {
+    const issue = String(flags.issue);
+    const lastDash = issue.lastIndexOf("-");
+
+    return (lastDash === -1 ? issue : issue.slice(0, lastDash)).toUpperCase();
+  }
+
+  return undefined;
+}
+
+/** Print the result of a GET/POST call, honoring --json. */
+function printResult(result, json, stdout) {
+  if (json) {
+    stdout(JSON.stringify({ ok: true, result }, null, 2));
+
+    return;
+  }
+
+  if (typeof result === "string") {
+    stdout(result);
+  } else {
+    stdout(JSON.stringify(result, null, 2));
+  }
+}
+
+/** Print an error, honoring --json, to stderr. */
+function printError(err, json, stderr) {
+  const code = err instanceof GatewayError ? err.code : err.name;
+
+  if (json) {
+    stderr(JSON.stringify({ ok: false, error: { code, message: err.message } }, null, 2));
+
+    return;
+  }
+
+  stderr(`error${code ? ` [${code}]` : ""}: ${err.message}`);
+}
+
+/**
+ * Run the CLI once.
+ * @param {string[]} argv args after node/script (i.e. `process.argv.slice(2)`)
+ * @param {{ stdout?: (s: string) => void, stderr?: (s: string) => void, request?: typeof gatewayRequest }} [io]
+ * @returns {Promise<number>} exit code
+ */
+export async function run(argv, io = {}) {
+  const stdout = io.stdout ?? ((s) => console.log(s));
+  const stderr = io.stderr ?? ((s) => console.error(s));
+  const request = io.request ?? gatewayRequest;
+
+  const { positionals, flags } = parseArgs(argv);
+
+  // Usage asked for is a success; usage printed because nothing was asked is an error.
+  if (flags.help || positionals.length === 0) {
+    stdout(USAGE);
+
+    return flags.help ? 0 : 1;
+  }
+
+  const match = resolveCommand(positionals);
+
+  if (!match) {
+    stderr(`Unknown command: "${positionals.join(" ")}". Run \`devflow --help\`.`);
+
+    return 1;
+  }
+
+  const { key, command, rest } = match;
+
+  let config;
+
+  try {
+    config = resolveConfig();
+  } catch (err) {
+    if (err instanceof ConfigError) {
+      printError(err, Boolean(flags.json), stderr);
+
+      return 1;
+    }
+
+    throw err;
+  }
+
+  try {
+    if (command.method === "GET") {
+      const result = await request(config, "GET", command.path);
+
+      printResult(result, Boolean(flags.json), stdout);
+
+      return 0;
+    }
+
+    // POST action: routing must be provided.
+    const projectKey = payloadProjectKey(flags);
+
+    if (!projectKey && !flags.profile) {
+      throw new UsageError(
+        `"${key}" needs a target: pass --issue, --project, or --profile. Usage: ${command.usage}`,
+      );
+    }
+
+    // Destructive gate: refuse before touching the gateway unless confirmed.
+    const confirmed = Boolean(flags.force || flags.yes);
+
+    if (command.destructive && !confirmed) {
+      throw new UsageError(
+        `"${key}" is destructive — re-run with --force (or --yes) to confirm. Usage: ${command.usage}`,
+      );
+    }
+
+    const action = command.resolveAction ? command.resolveAction(flags) : command.action;
+    const args = command.buildArgs ? command.buildArgs(rest, flags) : [];
+    const body = {
+      ...buildRoutingBody(flags),
+      ...(command.destructive ? { allowDestructive: true } : {}),
+      payload: {
+        projectKey,
+        ...(flags.repo ? { repo: String(flags.repo) } : {}),
+        args,
+      },
+    };
+
+    const result = await request(config, "POST", `/actions/${action}`, body);
+
+    printResult(result, Boolean(flags.json), stdout);
+
+    return 0;
+  } catch (err) {
+    if (err instanceof UsageError || err instanceof GatewayError) {
+      printError(err, Boolean(flags.json), stderr);
+
+      return 1;
+    }
+
+    throw err;
+  }
+}

package/src/client.js

@@ -0,0 +1,77 @@
+// Thin HTTP client of the local gateway. Sends the Bearer token, parses the
+// `{ ok, result, error }` envelope the server returns, and turns transport /
+// envelope failures into a tagged GatewayError the CLI can print clearly.
+
+/** A gateway call failure carrying the server's error `code` (when present). */
+export class GatewayError extends Error {
+  /** @param {string} message @param {string} [code] */
+  constructor(message, code) {
+    super(message);
+    this.name = "GatewayError";
+    this.code = code;
+  }
+}
+
+/**
+ * Turn a network-level failure into an actionable message. ECONNREFUSED almost
+ * always means the daemon isn't running.
+ * @param {unknown} err
+ * @param {string} baseUrl
+ */
+function describeTransportError(err, baseUrl) {
+  const cause = err?.cause ?? err;
+  const code = cause?.code;
+
+  if (code === "ECONNREFUSED") {
+    return new GatewayError(
+      `Cannot reach the DevFlow gateway at ${baseUrl}. Is the desktop app running?`,
+      "ECONNREFUSED",
+    );
+  }
+
+  return new GatewayError(`Gateway request failed: ${cause?.message ?? err}`, code);
+}
+
+/**
+ * Perform a gateway request and unwrap the response envelope.
+ * @param {{ baseUrl: string, token: string }} config
+ * @param {"GET" | "POST"} method
+ * @param {string} path e.g. `/actions/createBranch`
+ * @param {unknown} [body] JSON body for POST
+ * @returns {Promise<unknown>} the envelope's `result`
+ * @throws {GatewayError} on transport failure or an `{ ok: false }` envelope
+ */
+export async function gatewayRequest(config, method, path, body) {
+  const headers = { Authorization: `Bearer ${config.token}` };
+
+  if (body !== undefined) headers["Content-Type"] = "application/json";
+
+  let response;
+
+  try {
+    response = await fetch(`${config.baseUrl}${path}`, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+  } catch (err) {
+    throw describeTransportError(err, config.baseUrl);
+  }
+
+  let envelope;
+
+  try {
+    envelope = await response.json();
+  } catch {
+    throw new GatewayError(
+      `Gateway returned a non-JSON response (HTTP ${response.status}).`,
+      "BAD_RESPONSE",
+    );
+  }
+
+  if (envelope?.ok) return envelope.result;
+
+  const error = envelope?.error ?? {};
+
+  throw new GatewayError(error.message ?? `Gateway error (HTTP ${response.status}).`, error.code);
+}

package/src/commands.js

@@ -0,0 +1,277 @@
+// Command table: maps CLI verbs to gateway calls. Each command either GETs a
+// discovery route or POSTs an action whose `payload.args` mirrors the positional
+// signature of the matching Repo store action (see extension gatewayActions.ts).
+//
+// Routing (projectKey / issueKey / profile) is attached by cli.js from the global
+// flags; a command only builds its `args`.
+
+/** Parse a positional as an integer, or fail with a clear message. */
+function toInt(name, value) {
+  const n = Number.parseInt(value, 10);
+
+  if (!Number.isInteger(n)) {
+    throw new UsageError(`"${name}" must be an integer, got "${value}".`);
+  }
+
+  return n;
+}
+
+/** Parse a `--values` JSON-object flag into a plain object, or fail clearly. */
+function toValues(flag, raw) {
+  if (raw === undefined) return undefined;
+
+  let parsed;
+
+  try {
+    parsed = JSON.parse(String(raw));
+  } catch {
+    throw new UsageError(`"--${flag}" must be a JSON object, got "${raw}".`);
+  }
+
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new UsageError(`"--${flag}" must be a JSON object (e.g. '{"key":"val"}').`);
+  }
+
+  return parsed;
+}
+
+/** A bad-invocation error (wrong/missing args) — printed with the command usage. */
+export class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+  }
+}
+
+/**
+ * @typedef {Object} Command
+ * @property {"GET" | "POST"} method
+ * @property {string} [path]        For GET commands.
+ * @property {string} [action]      Gateway action name for POST commands.
+ * @property {boolean} [destructive] Requires --force/--yes (gated by cli.js).
+ * @property {(pos: string[], flags: Record<string, unknown>) => unknown[]} [buildArgs]
+ * @property {string} usage         One-line usage string.
+ */
+
+/** The command tree: `"group sub"` or a bare verb → {@link Command}. */
+const COMMANDS = {
+  "list-actions": {
+    method: "GET",
+    path: "/actions",
+    usage: "list-actions",
+  },
+  "list-profiles": {
+    method: "GET",
+    path: "/profiles",
+    usage: "list-profiles",
+  },
+
+  "branch create": {
+    method: "POST",
+    action: "createBranch",
+    usage: "branch create <branchName> (--issue|--project)",
+    buildArgs: ([branchName]) => {
+      if (!branchName) throw new UsageError("branch create requires <branchName>.");
+
+      return [branchName];
+    },
+  },
+  "branch delete": {
+    method: "POST",
+    action: "deleteBranch",
+    destructive: true,
+    usage: "branch delete <branchName> (--issue|--project) --force",
+    buildArgs: ([branchName]) => {
+      if (!branchName) throw new UsageError("branch delete requires <branchName>.");
+
+      return [branchName];
+    },
+  },
+
+  "commit template": {
+    method: "POST",
+    action: "commitByTemplate",
+    usage:
+      'commit template <worktreePath> [--values \'{"key":"val"}\'] [--no-push] (--issue|--project)',
+    buildArgs: ([worktreePath], flags) => {
+      if (!worktreePath) throw new UsageError("commit template requires <worktreePath>.");
+
+      const values = toValues("values", flags.values);
+      const push = flags["no-push"] ? false : undefined;
+
+      return [worktreePath, values, push];
+    },
+  },
+
+  "mr create": {
+    method: "POST",
+    action: "createPullRequest",
+    usage: "mr create <title> <headBranch> [--body <text>] (--issue|--project)",
+    buildArgs: ([title, headBranch], flags) => {
+      if (!title || !headBranch) {
+        throw new UsageError("mr create requires <title> and <headBranch>.");
+      }
+
+      return [title, flags.body ?? "", headBranch];
+    },
+  },
+  "mr ready": {
+    method: "POST",
+    action: "markPrReadyForReview",
+    usage: "mr ready <prId> (--issue|--project)",
+    buildArgs: ([prId]) => [toInt("prId", prId)],
+  },
+  "mr draft": {
+    method: "POST",
+    action: "markPrAsDraft",
+    usage: "mr draft <prId> (--issue|--project)",
+    buildArgs: ([prId]) => [toInt("prId", prId)],
+  },
+  "mr close": {
+    method: "POST",
+    action: "closePullRequest",
+    destructive: true,
+    usage: "mr close <prId> (--issue|--project) --force",
+    buildArgs: ([prId]) => [toInt("prId", prId)],
+  },
+  "mr assign": {
+    method: "POST",
+    action: "assignPr",
+    usage: "mr assign <prId> <assignee> (--issue|--project)",
+    buildArgs: ([prId, assignee]) => {
+      if (!assignee) throw new UsageError("mr assign requires <prId> and <assignee>.");
+
+      return [toInt("prId", prId), assignee];
+    },
+  },
+  "mr labels": {
+    method: "POST",
+    action: "addPrLabels",
+    usage: "mr labels <prId> <label...> (--issue|--project)",
+    buildArgs: ([prId, ...labels]) => {
+      if (labels.length === 0) {
+        throw new UsageError("mr labels requires <prId> and at least one <label>.");
+      }
+
+      return [toInt("prId", prId), labels];
+    },
+  },
+  "mr reviewers": {
+    method: "POST",
+    action: "requestPrReviewers",
+    usage: "mr reviewers <prId> <reviewer...> (--issue|--project)",
+    buildArgs: ([prId, ...reviewers]) => {
+      if (reviewers.length === 0) {
+        throw new UsageError("mr reviewers requires <prId> and at least one <reviewer>.");
+      }
+
+      return [toInt("prId", prId), reviewers];
+    },
+  },
+  "mr find": {
+    method: "POST",
+    action: "findPrByIssueKey",
+    usage: "mr find <issueKey> (--issue|--project)",
+    buildArgs: ([issueKey], flags) => {
+      const key = issueKey ?? flags.issue;
+
+      if (!key) throw new UsageError("mr find requires <issueKey> (or --issue).");
+
+      return [key];
+    },
+  },
+  "mr fix-prompt": {
+    method: "POST",
+    action: "getFixCommentsPrompt",
+    usage: "mr fix-prompt [prId] [--issue KEY] (--issue|--project)",
+    buildArgs: ([prId], flags) => {
+      const parsedPrId = prId === undefined ? undefined : toInt("prId", prId);
+      const issueKey = flags.issue ? String(flags.issue) : undefined;
+
+      return [parsedPrId, issueKey];
+    },
+  },
+  "pipeline status": {
+    method: "POST",
+    action: "getPipelineStatus",
+    usage: "pipeline status <prId> <headSha> (--issue|--project)",
+    buildArgs: ([prId, headSha]) => {
+      if (!headSha) throw new UsageError("pipeline status requires <prId> and <headSha>.");
+
+      return [{ prId: toInt("prId", prId), headSha }];
+    },
+  },
+  "pipeline jobs": {
+    method: "POST",
+    action: "listPipelineJobs",
+    usage: "pipeline jobs <prId> <headSha> (--issue|--project)",
+    buildArgs: ([prId, headSha]) => {
+      if (!headSha) throw new UsageError("pipeline jobs requires <prId> and <headSha>.");
+
+      return [{ prId: toInt("prId", prId), headSha }];
+    },
+  },
+  "pipeline retry": {
+    method: "POST",
+    action: "restartFailedJobs",
+    usage: "pipeline retry <pipelineOrRunId> [--all] [--job <jobId>] (--issue|--project)",
+    buildArgs: ([id], flags) => {
+      if (flags.job !== undefined) return [toInt("job", String(flags.job))];
+
+      const target = toInt("pipelineOrRunId", id);
+
+      return [target];
+    },
+    // `retry` maps to restartFailedJobs by default; --all → restartAllJobs, --job → restartPipelineJob.
+    resolveAction: (flags) => {
+      if (flags.job !== undefined) return "restartPipelineJob";
+      if (flags.all) return "restartAllJobs";
+
+      return "restartFailedJobs";
+    },
+  },
+
+  "slack notify": {
+    method: "POST",
+    action: "notifySlack",
+    usage: 'slack notify <message> [--channel ID] [--values \'{"key":"val"}\'] (--issue|--project)',
+    buildArgs: ([message], flags) => {
+      if (!message) throw new UsageError("slack notify requires <message>.");
+
+      const channel = flags.channel ? String(flags.channel) : undefined;
+      const values = toValues("values", flags.values);
+
+      return [message, channel, values];
+    },
+  },
+};
+
+/** Every command key (for help / discovery). */
+export function listCommands() {
+  return Object.keys(COMMANDS);
+}
+
+/**
+ * Resolve a command from the leading positionals. Tries a two-word key
+ * (`group sub`) first, then a one-word key. Returns the command plus the
+ * remaining positionals it consumes.
+ * @param {string[]} positionals
+ * @returns {{ key: string, command: Command, rest: string[] } | null}
+ */
+export function resolveCommand(positionals) {
+  if (positionals.length === 0) return null;
+
+  const two = positionals.slice(0, 2).join(" ");
+
+  if (positionals.length >= 2 && COMMANDS[two]) {
+    return { key: two, command: COMMANDS[two], rest: positionals.slice(2) };
+  }
+
+  const one = positionals[0];
+
+  if (COMMANDS[one]) {
+    return { key: one, command: COMMANDS[one], rest: positionals.slice(1) };
+  }
+
+  return null;
+}

package/src/config.js

@@ -0,0 +1,94 @@
+// Resolves how the CLI reaches the local gateway: base URL (port) and the Bearer
+// token. The token is read from the same userData dir the desktop daemon writes it
+// to (see desktop/src/gateway/token.js) so scripts "just work" with no setup. Env
+// vars override for tests / non-standard installs.
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+/** Loopback host — the gateway only ever binds 127.0.0.1. */
+const HOST = "127.0.0.1";
+/** Default gateway port (matches desktop server DEFAULT_PORT). */
+const DEFAULT_PORT = 8787;
+/** Token filename under the app's userData dir (matches token.js TOKEN_FILE). */
+const TOKEN_FILE = "gateway-token";
+
+/** A tagged config-resolution failure, so the CLI can print a clear message. */
+export class ConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+}
+
+/**
+ * The daemon's userData dir, matching desktop/src/gateway/token.js's fallback
+ * (the CLI runs under plain node, never Electron, so it always uses the fallback).
+ * @returns {string}
+ */
+function resolveDataDir() {
+  const home = os.homedir();
+
+  if (process.platform === "darwin") {
+    return path.join(home, "Library", "Application Support", "devflow");
+  }
+
+  if (process.platform === "win32") {
+    const base = process.env.APPDATA || path.join(home, "AppData", "Roaming");
+
+    return path.join(base, "devflow");
+  }
+
+  return path.join(home, ".config", "devflow");
+}
+
+/** Resolve the gateway port from `DEVFLOW_GATEWAY_PORT`, else the default. */
+function resolvePort() {
+  const port = Number.parseInt(process.env.DEVFLOW_GATEWAY_PORT, 10);
+
+  return Number.isInteger(port) && port > 0 && port < 65536 ? port : DEFAULT_PORT;
+}
+
+/**
+ * Read the gateway token: `DEVFLOW_GATEWAY_TOKEN` wins, else the token file the
+ * daemon persisted. Throws {@link ConfigError} with an actionable message when
+ * neither is available.
+ * @returns {string}
+ */
+function resolveToken() {
+  const fromEnv = process.env.DEVFLOW_GATEWAY_TOKEN?.trim();
+
+  if (fromEnv) return fromEnv;
+
+  const tokenPath = path.join(resolveDataDir(), TOKEN_FILE);
+
+  try {
+    const token = fs.readFileSync(tokenPath, "utf8").trim();
+
+    if (token) return token;
+
+    throw new ConfigError(`Gateway token file is empty: ${tokenPath}`);
+  } catch (err) {
+    if (err instanceof ConfigError) throw err;
+
+    throw new ConfigError(
+      `Could not read the gateway token at ${tokenPath}. ` +
+        `Is the DevFlow desktop app running? ` +
+        `(Or set DEVFLOW_GATEWAY_TOKEN to override.)`,
+    );
+  }
+}
+
+/**
+ * Resolve the full CLI runtime config.
+ * @returns {{ baseUrl: string, token: string }}
+ */
+export function resolveConfig() {
+  const port = resolvePort();
+
+  return {
+    baseUrl: `http://${HOST}:${port}`,
+    token: resolveToken(),
+  };
+}