unirepo-cli 0.2.1 → 0.4.0

package/README.md

@@ -142,6 +142,7 @@ AI coding agents work best when they can see the full change at once.
 | `status` | Show subtrees, branches, and what changed |
 | `branch [name]` | Create or show the current push branch |
 | `push [subtree...]` | Push changed subtrees upstream |
+| `pr [subtree...]` | Open pull requests for changed subtree repos |
 
 
 ### init
@@ -173,13 +174,14 @@ Adds a repo to an existing workspace. The directory name defaults to the repo na
 ### pull
 
 ```bash
-unirepo pull [subtree...]
+unirepo pull [subtree...] [--prefix <name>]
 ```
 
-Pulls upstream changes. Without arguments, pulls all tracked subtrees.
+Pulls upstream changes. Without arguments, pulls all tracked subtrees. When you use `--branch` without naming a subtree, `unirepo` skips tracked subtrees that do not have that upstream branch.
 
 | Flag | Effect |
 | --- | --- |
+| `--prefix <name>` | Pull only one tracked subtree |
 | `--branch <name>` | Pull a specific upstream branch |
 | `--full-history` | Pull full history instead of squash |
 
@@ -212,6 +214,24 @@ Pushes changed subtrees upstream. Without arguments, auto-detects which subtrees
 | `--branch <name>` | Override the upstream branch name |
 | `--dry-run` | Show what would run without executing |
 
+### pr
+
+```bash
+unirepo pr [subtree...] --title <title> [--body <text>]
+```
+
+Opens one GitHub pull request per changed subtree repo. Without subtree arguments, `unirepo` auto-detects changed subtrees. Use explicit subtree names when you want PRs for only part of the workspace.
+
+
+| Flag | Effect |
+| --- | --- |
+| `--title <title>` | Shared PR title for all selected repos |
+| `--body <text>` | Shared PR description |
+| `--base <name>` | Override the base branch for all selected repos |
+| `--head <name>` | Override the head branch name (default: current branch) |
+| `--draft` | Create draft pull requests |
+| `--dry-run` | Show the `gh pr create` commands without executing |
+
 
 ## How It Works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unirepo-cli",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "CLI tool for creating and managing git-subtree monorepos — run your agents across repos",
   "type": "module",
   "bin": {

package/src/commands/add.js

@@ -1,4 +1,4 @@
-import { git, detectDefaultBranch, extractRepoName } from '../git.js';
+import { git, detectDefaultBranch, extractRepoName, setConfiguredSubtreeBranch } from '../git.js';
 import { validateGitSubtree, validateUrls, validateInsideMonorepo, validateNameAvailable, validateReachable } from '../validate.js';
 import * as ui from '../ui.js';
 
@@ -39,6 +39,8 @@ export async function runAdd({ url, prefix, branch, fullHistory }) {
     git(`subtree add --squash --prefix="${name}" "${name}" "${upstreamBranch}"`, { cwd });
   }
 
+  setConfiguredSubtreeBranch(cwd, name, upstreamBranch);
+
   // ── Done ─────────────────────────────────────────────────────────────────
   ui.step(4, 4, 'Done!');
   ui.addSummary(name, url);

package/src/commands/branch.js

@@ -1,4 +1,4 @@
-import { git, getCurrentBranch, getSubtreePrefixes, getRemoteBranch } from '../git.js';
+import { git, getCurrentBranch, getSubtreePrefixes, getTrackedSubtreeBranch } from '../git.js';
 import { validateInsideMonorepo } from '../validate.js';
 import * as ui from '../ui.js';
 
@@ -17,7 +17,7 @@ export async function runBranch({ name }) {
     ui.info(`Current branch: ${currentBranch}`);
     ui.blank();
     for (const s of subtrees) {
-      const upstream = getRemoteBranch(cwd, s.name) || 'unknown';
+      const upstream = getTrackedSubtreeBranch(cwd, s.name) || 'unknown';
       ui.info(`  ${s.name}  upstream: ${upstream}  push target: ${currentBranch}`);
     }
     ui.blank();
@@ -49,6 +49,6 @@ export async function runBranch({ name }) {
   ui.info('  1. Make changes in subtree directories');
   ui.info('  2. Commit in the monorepo');
   ui.info(`  3. unirepo push`);
-  ui.info('  4. Open one PR per upstream repo');
+  ui.info('  4. unirepo pr --title "..." --body "..."');
   ui.blank();
 }

package/src/commands/init.js

@@ -1,6 +1,6 @@
 import { mkdirSync, writeFileSync, existsSync, rmSync } from 'node:fs';
 import { resolve, join } from 'node:path';
-import { git, detectDefaultBranch, extractRepoName } from '../git.js';
+import { git, detectDefaultBranch, extractRepoName, setConfiguredSubtreeBranch } from '../git.js';
 import { validateGitSubtree, validateUrls, validateNoDuplicateNames, validateReachable } from '../validate.js';
 import { AGENTS_MD, GITIGNORE } from '../templates.js';
 import * as ui from '../ui.js';
@@ -79,6 +79,8 @@ export async function runInit({ dir, repos, fullHistory }) {
         git(`subtree add --squash --prefix="${name}" "${name}" "${branch}"`, { cwd: absDir });
       }
 
+      setConfiguredSubtreeBranch(absDir, name, branch);
+
       ui.success(`${name} imported`);
     }
   } catch (err) {

package/src/commands/pr.js

@@ -0,0 +1,175 @@
+import {
+  getCurrentBranch,
+  getSubtreePrefixes,
+  getChangedSubtrees,
+  getTrackedSubtreeBranch,
+  hasRemoteBranch,
+} from '../git.js';
+import { isGhAvailable, getGitHubRepoSlugFromUrl, createPullRequest } from '../github.js';
+import { validateInsideMonorepo } from '../validate.js';
+import * as ui from '../ui.js';
+
+function quoteShellArg(value) {
+  return JSON.stringify(value);
+}
+
+export function selectPrSubtrees(allPrefixes, changedPrefixes, requestedSubtrees) {
+  if (!requestedSubtrees || requestedSubtrees.length === 0) {
+    return changedPrefixes;
+  }
+
+  const prefixNames = new Set(allPrefixes.map((prefix) => prefix.name));
+  for (const name of requestedSubtrees) {
+    if (!prefixNames.has(name)) {
+      throw new Error(`"${name}" is not a tracked subtree. Run "unirepo status" to see available subtrees.`);
+    }
+  }
+
+  return allPrefixes.filter((prefix) => requestedSubtrees.includes(prefix.name));
+}
+
+export function resolvePrBaseBranch({ requestedBase, trackedBranch }) {
+  return requestedBase || trackedBranch || 'main';
+}
+
+export function planPrTargets({
+  allPrefixes,
+  changedPrefixes,
+  requestedSubtrees,
+  requestedBase,
+  headBranch,
+  getTrackedBranchFn = () => null,
+  getRepoSlugFn = () => null,
+}) {
+  return selectPrSubtrees(allPrefixes, changedPrefixes, requestedSubtrees).map((prefix) => ({
+    name: prefix.name,
+    repo: getRepoSlugFn(prefix.url),
+    url: prefix.url,
+    base: resolvePrBaseBranch({
+      requestedBase,
+      trackedBranch: getTrackedBranchFn(prefix.name),
+    }),
+    head: headBranch,
+  }));
+}
+
+export async function runPr({ subtrees: requestedSubtrees, title, body, base, head, draft, dryRun }) {
+  const cwd = process.cwd();
+
+  ui.header('Creating pull requests');
+  ui.blank();
+
+  validateInsideMonorepo(cwd);
+
+  if (!isGhAvailable()) {
+    throw new Error('GitHub CLI is not available or not authenticated. Install gh and run "gh auth login".');
+  }
+
+  const currentBranch = getCurrentBranch(cwd);
+  const headBranch = head || currentBranch;
+  const allPrefixes = getSubtreePrefixes(cwd);
+  const changedPrefixes = getChangedSubtrees(cwd);
+  const targets = planPrTargets({
+    allPrefixes,
+    changedPrefixes,
+    requestedSubtrees,
+    requestedBase: base,
+    headBranch,
+    getTrackedBranchFn: (prefixName) => getTrackedSubtreeBranch(cwd, prefixName),
+    getRepoSlugFn: getGitHubRepoSlugFromUrl,
+  });
+
+  if (targets.length === 0) {
+    ui.info('No changed subtrees detected. Nothing to open PRs for.');
+    ui.info('Push a changed subtree first or pass explicit subtree names.');
+    ui.blank();
+    return;
+  }
+
+  ui.info(`Head branch: ${headBranch}`);
+  ui.info(`Subtrees: ${targets.map((target) => target.name).join(', ')}`);
+  ui.blank();
+
+  const dryRunCommands = [];
+  let succeeded = 0;
+  let failed = 0;
+
+  for (let i = 0; i < targets.length; i++) {
+    const target = targets[i];
+
+    ui.repoStep(i + 1, targets.length, target.name, dryRun ? 'Planning PR for' : 'Opening PR for');
+    ui.repoDetail('Repo', target.repo || target.url);
+    ui.repoDetail('Base', target.base);
+    ui.repoDetail('Head', target.head);
+
+    if (!target.repo) {
+      ui.error(`Failed to open PR for ${target.name}: remote URL is not a GitHub repository.`);
+      failed++;
+      ui.blank();
+      continue;
+    }
+
+    if (!hasRemoteBranch(cwd, target.name, target.head)) {
+      ui.error(`Failed to open PR for ${target.name}: upstream branch "${target.head}" does not exist. Run "unirepo push ${target.name}" first.`);
+      failed++;
+      ui.blank();
+      continue;
+    }
+
+    if (!hasRemoteBranch(cwd, target.name, target.base)) {
+      ui.error(`Failed to open PR for ${target.name}: base branch "${target.base}" does not exist upstream.`);
+      failed++;
+      ui.blank();
+      continue;
+    }
+
+    const ghCommand = [
+      'gh pr create',
+      `--repo ${quoteShellArg(target.repo)}`,
+      `--base ${quoteShellArg(target.base)}`,
+      `--head ${quoteShellArg(target.head)}`,
+      `--title ${quoteShellArg(title)}`,
+      `--body ${quoteShellArg(body)}`,
+      draft ? '--draft' : '',
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    if (dryRun) {
+      dryRunCommands.push(ghCommand);
+      succeeded++;
+      ui.success(`${target.name} PR planned`);
+      ui.blank();
+      continue;
+    }
+
+    try {
+      const url = createPullRequest({
+        repo: target.repo,
+        base: target.base,
+        head: target.head,
+        title,
+        body,
+        draft,
+      });
+      ui.success(`${target.name} PR opened${url ? `: ${url}` : ''}`);
+      succeeded++;
+    } catch (err) {
+      ui.error(`Failed to open PR for ${target.name}: ${err.message}`);
+      failed++;
+    }
+
+    ui.blank();
+  }
+
+  if (dryRunCommands.length > 0) {
+    ui.dryRun(dryRunCommands);
+  }
+
+  if (failed === 0) {
+    ui.success(`${dryRun ? 'Planned' : 'Opened'} ${succeeded} pull request(s)`);
+  } else {
+    ui.warning(`${dryRun ? 'Planned' : 'Opened'} ${succeeded}, ${failed} failed`);
+  }
+  ui.blank();
+}

package/src/commands/pull.js

@@ -1,7 +1,53 @@
-import { git, getRemoteBranch, getSubtreePrefixes } from '../git.js';
+import { git, getSubtreePrefixes, getTrackedSubtreeBranch, hasRemoteBranch, setConfiguredSubtreeBranch } from '../git.js';
 import { validateGitSubtree, validateInsideMonorepo } from '../validate.js';
 import * as ui from '../ui.js';
 
+export function selectPullSubtrees(allPrefixes, requestedSubtrees) {
+  if (!requestedSubtrees || requestedSubtrees.length === 0) {
+    return allPrefixes;
+  }
+
+  const prefixNames = new Set(allPrefixes.map((prefix) => prefix.name));
+  for (const name of requestedSubtrees) {
+    if (!prefixNames.has(name)) {
+      throw new Error(`"${name}" is not a tracked subtree. Run "unirepo status" to see available subtrees.`);
+    }
+  }
+
+  return allPrefixes.filter((prefix) => requestedSubtrees.includes(prefix.name));
+}
+
+export function planPullTargets({
+  allPrefixes,
+  requestedSubtrees,
+  branch,
+  hasRemoteBranchFn = () => true,
+}) {
+  const explicitSelection = Boolean(requestedSubtrees && requestedSubtrees.length > 0);
+  const selectedPrefixes = selectPullSubtrees(allPrefixes, requestedSubtrees);
+
+  if (!branch || explicitSelection) {
+    return { toPull: selectedPrefixes, skipped: [] };
+  }
+
+  const toPull = [];
+  const skipped = [];
+
+  for (const prefix of selectedPrefixes) {
+    if (hasRemoteBranchFn(prefix.name, branch)) {
+      toPull.push(prefix);
+    } else {
+      skipped.push(prefix);
+    }
+  }
+
+  return { toPull, skipped };
+}
+
+export function resolvePullUpstreamBranch({ requestedBranch, trackedBranch }) {
+  return requestedBranch || trackedBranch || 'main';
+}
+
 export async function runPull({ subtrees: requestedSubtrees, branch, fullHistory }) {
   const cwd = process.cwd();
 
@@ -12,32 +58,38 @@ export async function runPull({ subtrees: requestedSubtrees, branch, fullHistory
   validateInsideMonorepo(cwd);
 
   const allPrefixes = getSubtreePrefixes(cwd);
-  let toPull;
-
-  if (requestedSubtrees && requestedSubtrees.length > 0) {
-    const prefixNames = new Set(allPrefixes.map((prefix) => prefix.name));
-    for (const name of requestedSubtrees) {
-      if (!prefixNames.has(name)) {
-        throw new Error(`"${name}" is not a tracked subtree. Run "unirepo status" to see available subtrees.`);
-      }
-    }
-    toPull = allPrefixes.filter((prefix) => requestedSubtrees.includes(prefix.name));
-  } else {
-    toPull = allPrefixes;
-  }
+  const { toPull, skipped } = planPullTargets({
+    allPrefixes,
+    requestedSubtrees,
+    branch,
+    hasRemoteBranchFn: (remoteName, branchName) => hasRemoteBranch(cwd, remoteName, branchName),
+  });
 
   if (toPull.length === 0) {
-    ui.info('No tracked subtrees found. Nothing to pull.');
+    if (branch && skipped.length > 0) {
+      ui.info(`No tracked subtrees have upstream branch "${branch}". Nothing to pull.`);
+    } else {
+      ui.info('No tracked subtrees found. Nothing to pull.');
+    }
     ui.blank();
     return;
   }
 
+  if (skipped.length > 0) {
+    ui.warning(`Skipping ${skipped.map((prefix) => prefix.name).join(', ')}: no upstream branch "${branch}"`);
+    ui.blank();
+  }
+
   let succeeded = 0;
   let failed = 0;
 
   for (let i = 0; i < toPull.length; i++) {
     const prefix = toPull[i];
-    const upstreamBranch = branch || getRemoteBranch(cwd, prefix.name) || 'main';
+    const trackedBranch = getTrackedSubtreeBranch(cwd, prefix.name);
+    const upstreamBranch = resolvePullUpstreamBranch({
+      requestedBranch: branch,
+      trackedBranch,
+    });
     const squashFlag = fullHistory ? '' : '--squash ';
 
     ui.repoStep(i + 1, toPull.length, prefix.name, 'Pulling');
@@ -46,6 +98,7 @@ export async function runPull({ subtrees: requestedSubtrees, branch, fullHistory
 
     try {
       git(`subtree pull ${squashFlag}--prefix="${prefix.name}" "${prefix.name}" "${upstreamBranch}"`, { cwd });
+      setConfiguredSubtreeBranch(cwd, prefix.name, upstreamBranch);
       ui.success(`${prefix.name} pulled`);
       succeeded++;
     } catch (err) {
@@ -56,10 +109,12 @@ export async function runPull({ subtrees: requestedSubtrees, branch, fullHistory
     ui.blank();
   }
 
-  if (failed === 0) {
+  if (failed === 0 && skipped.length === 0) {
     ui.success(`All ${succeeded} subtree(s) pulled`);
+  } else if (failed === 0) {
+    ui.success(`${succeeded} subtree(s) pulled, ${skipped.length} skipped`);
   } else {
-    ui.warning(`${succeeded} pulled, ${failed} failed`);
+    ui.warning(`${succeeded} pulled, ${failed} failed${skipped.length > 0 ? `, ${skipped.length} skipped` : ''}`);
   }
   ui.blank();
-}
+}

package/src/commands/status.js

@@ -1,4 +1,4 @@
-import { getCurrentBranch, getSubtreePrefixes, getChangedSubtrees, getRemoteBranch } from '../git.js';
+import { getCurrentBranch, getSubtreePrefixes, getChangedSubtrees, getTrackedSubtreeBranch } from '../git.js';
 import { validateInsideMonorepo } from '../validate.js';
 import * as ui from '../ui.js';
 
@@ -15,7 +15,7 @@ export async function runStatus({ json }) {
   const subtrees = prefixes.map((p) => ({
     name: p.name,
     url: p.url,
-    upstream: getRemoteBranch(cwd, p.name) || 'unknown',
+    upstream: getTrackedSubtreeBranch(cwd, p.name) || 'unknown',
     pushBranch: branch,
     changed: changedNames.has(p.name),
   }));

package/src/git.js

@@ -2,6 +2,14 @@ import { execSync } from 'node:child_process';
 import { readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 
+function quoteShellArg(value) {
+  return JSON.stringify(value);
+}
+
+function getSubtreeBranchConfigKey(prefixName) {
+  return `unirepo.subtree.${prefixName}.branch`;
+}
+
 /**
  * Execute a git command and return trimmed stdout.
  * @param {string} args - git arguments
@@ -213,21 +221,93 @@ export function getChangedSubtrees(cwd) {
  */
 export function getRemoteBranch(cwd, remoteName) {
   try {
-    const refs = execSync(`git branch -r --list "${remoteName}/*"`, {
+    const headRef = execSync(`git symbolic-ref --quiet --short "refs/remotes/${remoteName}/HEAD"`, {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    if (headRef) {
+      const slash = headRef.indexOf('/');
+      return slash >= 0 ? headRef.slice(slash + 1) : headRef;
+    }
+  } catch {
+    // fall through
+  }
+
+  try {
+    const refs = execSync(`git for-each-ref --format="%(refname:short)" "refs/remotes/${remoteName}"`, {
       cwd,
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'pipe'],
     }).trim();
     if (!refs) return null;
-    // e.g. "Hello-World/master" → "master"
-    const first = refs.split('\n')[0].trim();
-    const slash = first.indexOf('/');
-    return slash >= 0 ? first.slice(slash + 1) : first;
+
+    const branches = refs
+      .split('\n')
+      .map((ref) => ref.trim())
+      .filter(Boolean)
+      .map((ref) => {
+        const slash = ref.indexOf('/');
+        return slash >= 0 ? ref.slice(slash + 1) : ref;
+      })
+      .filter((ref) => ref !== 'HEAD');
+
+    if (branches.length === 0) {
+      return null;
+    }
+
+    if (branches.includes('main')) return 'main';
+    if (branches.includes('master')) return 'master';
+    return branches[0];
   } catch {
     return null;
   }
 }
 
+/**
+ * Get the branch explicitly tracked for a subtree in local git config.
+ */
+export function getConfiguredSubtreeBranch(cwd, prefixName) {
+  const branch = git(`config --get ${quoteShellArg(getSubtreeBranchConfigKey(prefixName))}`, {
+    cwd,
+    silent: true,
+    allowFailure: true,
+  });
+  return branch || null;
+}
+
+/**
+ * Persist the branch currently tracked for a subtree in local git config.
+ */
+export function setConfiguredSubtreeBranch(cwd, prefixName, branch) {
+  git(
+    `config ${quoteShellArg(getSubtreeBranchConfigKey(prefixName))} ${quoteShellArg(branch)}`,
+    { cwd, silent: true }
+  );
+}
+
+/**
+ * Get the branch unirepo should treat as the subtree's upstream branch.
+ */
+export function getTrackedSubtreeBranch(cwd, prefixName) {
+  return getConfiguredSubtreeBranch(cwd, prefixName) || getRemoteBranch(cwd, prefixName);
+}
+
+/**
+ * Check whether a remote has a specific branch.
+ */
+export function hasRemoteBranch(cwd, remoteName, branch) {
+  try {
+    execSync(`git ls-remote --exit-code --heads "${remoteName}" "${branch}"`, {
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Check if the working tree has uncommitted (staged or unstaged) changes.
  */

package/src/github.js

@@ -1,4 +1,4 @@
-import { execSync } from 'node:child_process';
+import { execFileSync, execSync } from 'node:child_process';
 
 /**
  * Thin wrapper around the `gh` CLI. We shell out rather than hitting the
@@ -23,6 +23,19 @@ function runGh(args, { timeout = 30000 } = {}) {
   }
 }
 
+function runGhArgs(args, { timeout = 30000 } = {}) {
+  try {
+    return execFileSync('gh', args, {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout,
+    });
+  } catch (err) {
+    const stderr = (err.stderr || '').toString().trim();
+    throw new Error(stderr || err.message);
+  }
+}
+
 function runGhJson(args, opts) {
   const out = runGh(args, opts);
   if (!out.trim()) return [];
@@ -111,3 +124,49 @@ export function searchRepos(query, limit = SEARCH_LIMIT) {
     isPrivate: r.isPrivate,
   }));
 }
+
+export function getGitHubRepoSlugFromUrl(url) {
+  const trimmed = url.replace(/\/$/, '').replace(/\.git$/, '');
+  const patterns = [
+    /^https?:\/\/github\.com\/([^/]+)\/([^/]+)$/i,
+    /^git@github\.com:([^/]+)\/([^/]+)$/i,
+    /^ssh:\/\/git@github\.com\/([^/]+)\/([^/]+)$/i,
+  ];
+
+  for (const pattern of patterns) {
+    const match = trimmed.match(pattern);
+    if (match) {
+      return `${match[1]}/${match[2]}`;
+    }
+  }
+
+  return null;
+}
+
+export function createPullRequest({ repo, base, head, title, body, draft = false }) {
+  const args = [
+    'pr',
+    'create',
+    '--repo',
+    repo,
+    '--base',
+    base,
+    '--head',
+    head,
+    '--title',
+    title,
+    '--body',
+    body,
+  ];
+
+  if (draft) {
+    args.push('--draft');
+  }
+
+  const output = runGhArgs(args);
+  const lines = output
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+  return lines.at(-1) || '';
+}

package/src/index.js

@@ -8,6 +8,7 @@ import { runPull } from './commands/pull.js';
 import { runStatus } from './commands/status.js';
 import { runPush } from './commands/push.js';
 import { runBranch } from './commands/branch.js';
+import { runPr } from './commands/pr.js';
 import { pathToFileURL } from 'node:url';
 import { realpathSync } from 'node:fs';
 
@@ -37,10 +38,20 @@ export function parseArgs(argv) {
       flags.json = true;
     } else if (arg === '--dry-run') {
       flags.dryRun = true;
+    } else if (arg === '--draft') {
+      flags.draft = true;
     } else if (arg === '--prefix' && i + 1 < args.length) {
       flags.prefix = args[++i];
     } else if (arg === '--branch' && i + 1 < args.length) {
       flags.branch = args[++i];
+    } else if (arg === '--title' && i + 1 < args.length) {
+      flags.title = args[++i];
+    } else if (arg === '--body' && i + 1 < args.length) {
+      flags.body = args[++i];
+    } else if (arg === '--base' && i + 1 < args.length) {
+      flags.base = args[++i];
+    } else if (arg === '--head' && i + 1 < args.length) {
+      flags.head = args[++i];
     } else if (arg === '--help' || arg === '-h') {
       flags.help = true;
     } else if (arg.startsWith('-')) {
@@ -54,6 +65,59 @@ export function parseArgs(argv) {
   return { command, positional, flags };
 }
 
+const COMMAND_USAGE = {
+  init: 'Usage: unirepo init <dir> <repo-url> [repo-url...]',
+  add: 'Usage: unirepo add <repo-url> [--prefix <name>] [--branch <name>] [--full-history]',
+  pull: 'Usage: unirepo pull [subtree...] [--prefix <name>] [--branch <name>] [--full-history]',
+  status: 'Usage: unirepo status [--json]',
+  push: 'Usage: unirepo push [subtree...] [--branch <name>] [--dry-run]',
+  branch: 'Usage: unirepo branch [name]',
+  pr: 'Usage: unirepo pr [subtree...] --title <title> [--body <text>] [--base <name>] [--head <name>] [--draft] [--dry-run]',
+};
+
+const COMMAND_FLAGS = {
+  version: new Set(),
+  init: new Set(['fullHistory']),
+  add: new Set(['prefix', 'branch', 'fullHistory']),
+  pull: new Set(['prefix', 'branch', 'fullHistory']),
+  status: new Set(['json']),
+  push: new Set(['branch', 'dryRun']),
+  branch: new Set(),
+  pr: new Set(['title', 'body', 'base', 'head', 'draft', 'dryRun']),
+};
+
+const FLAG_NAMES = {
+  fullHistory: '--full-history',
+  json: '--json',
+  dryRun: '--dry-run',
+  prefix: '--prefix',
+  branch: '--branch',
+  title: '--title',
+  body: '--body',
+  base: '--base',
+  head: '--head',
+  draft: '--draft',
+};
+
+export function validateCommandFlags(command, flags) {
+  const allowedFlags = COMMAND_FLAGS[command];
+  if (!allowedFlags) {
+    return;
+  }
+
+  const unsupportedFlags = Object.keys(flags)
+    .filter((flag) => flag !== 'help' && !allowedFlags.has(flag))
+    .map((flag) => FLAG_NAMES[flag] || `--${flag}`);
+
+  if (unsupportedFlags.length === 0) {
+    return;
+  }
+
+  const label = unsupportedFlags.length === 1 ? 'Flag' : 'Flags';
+  const verb = unsupportedFlags.length === 1 ? 'is' : 'are';
+  throw new Error(`${label} ${unsupportedFlags.join(', ')} ${verb} not supported for "${command}".`);
+}
+
 // ── Main ───────────────────────────────────────────────────────────────────────
 
 export async function main() {
@@ -64,6 +128,17 @@ export async function main() {
     process.exit(0);
   }
 
+  try {
+    validateCommandFlags(command, flags);
+  } catch (err) {
+    ui.error(err.message);
+    const usage = COMMAND_USAGE[command];
+    if (usage) {
+      ui.info(usage);
+    }
+    process.exit(1);
+  }
+
   switch (command) {
     case 'version': {
       ui.version();
@@ -102,8 +177,13 @@ export async function main() {
     }
 
     case 'pull': {
+      if (flags.prefix && positional.length > 0) {
+        ui.error('Usage: unirepo pull [subtree...] [--prefix <name>] [--branch <name>] [--full-history]');
+        ui.info('Use either subtree arguments or --prefix, not both.');
+        process.exit(1);
+      }
       await runPull({
-        subtrees: positional.length > 0 ? positional : undefined,
+        subtrees: flags.prefix ? [flags.prefix] : positional.length > 0 ? positional : undefined,
         branch: flags.branch,
         fullHistory: flags.fullHistory || false,
       });
@@ -129,6 +209,24 @@ export async function main() {
       break;
     }
 
+    case 'pr': {
+      if (!flags.title) {
+        ui.error('Usage: unirepo pr [subtree...] --title <title> [--body <text>] [--base <name>] [--head <name>] [--draft] [--dry-run]');
+        ui.info('Provide a shared PR title with --title. Use --body to set the description.');
+        process.exit(1);
+      }
+      await runPr({
+        subtrees: positional.length > 0 ? positional : undefined,
+        title: flags.title,
+        body: flags.body || '',
+        base: flags.base,
+        head: flags.head,
+        draft: flags.draft || false,
+        dryRun: flags.dryRun || false,
+      });
+      break;
+    }
+
     default:
       ui.error(`Unknown command: ${command}`);
       ui.blank();

package/src/templates.js

@@ -30,14 +30,16 @@ unirepo branch <branch>
 unirepo pull
 unirepo push --dry-run
 unirepo push
+unirepo pr --title "feat: ..." --body "..."
 unirepo add <repo-url> --branch <branch>
 \`\`\`
 
 - \`status\` shows tracked subtrees, upstream branches, the current push branch, and changed files.
 - \`branch <name>\` creates the local branch name you should reuse when pushing subtrees upstream.
-- \`pull\` updates one or more tracked subtrees from upstream before or during your work.
+- \`pull\` updates one or more tracked subtrees from upstream before or during your work. Use \`--prefix\` when you want a branch-specific pull for just one subtree.
 - \`push --dry-run\` is the safe first step before a real push.
 - \`push\` without subtree names auto-detects changed subtrees. \`push <subtree>\` pushes one subtree.
+- \`pr\` opens one PR per changed or explicitly selected subtree repo after those branches have been pushed.
 - \`add\` imports another repository as a subtree. Use \`--branch\` to import from a non-default upstream branch.
 
 ## Workflow
@@ -56,6 +58,7 @@ git checkout -b <branch>
 CLI:
 \`\`\`bash
 unirepo pull
+unirepo pull --prefix <subtree> --branch <branch>
 \`\`\`
 Git:
 \`\`\`bash
@@ -92,6 +95,13 @@ Git:
 git subtree push --prefix=<subtree> <remote-or-url> <branch>
 \`\`\`
 
+7. Open one PR per upstream subtree repo after push.
+CLI:
+\`\`\`bash
+unirepo pr --title "feat: ..." --body "..."
+unirepo pr <subtree> --title "feat: ..."
+\`\`\`
+
 ## Raw Git Subtree
 
 Use these when operating without the CLI:
@@ -115,6 +125,7 @@ git subtree push --prefix=libfoo https://github.com/example/libfoo.git <branch>
 - Open one PR per upstream subtree repo.
 - Use the same branch name in each upstream repo.
 - Target the default branch of the upstream repo unless that repo's workflow says otherwise.
+- Run \`unirepo pr\` only after the head branch exists upstream for that subtree repo.
 - Ensure each PR contains only changes from its own subtree.
 `;
 

package/src/ui.js

@@ -179,6 +179,7 @@ ${chalk.bold('Commands:')}
   ${chalk.green('pull')} [subtree...]            Pull subtree updates from upstream
   ${chalk.green('status')}                      Show tracked subtrees and changes
   ${chalk.green('push')} [subtree...]            Push changed subtrees upstream
+  ${chalk.green('pr')}   [subtree...]            Open PRs for changed subtree repos
   ${chalk.green('branch')} [name]               Create a branch on all upstream repos
   ${chalk.green('version')}                     Show the installed CLI version
 
@@ -195,6 +196,7 @@ ${chalk.bold('Add options:')}
   --full-history              Import full git history
 
 ${chalk.bold('Pull options:')}
+  --prefix <name>             Pull only one tracked subtree
   --branch <name>             Pull a specific upstream branch for all selected subtrees
   --full-history              Pull full history instead of squash mode
 
@@ -205,6 +207,14 @@ ${chalk.bold('Push options:')}
   --branch <name>             Branch name for upstream push (default: current)
   --dry-run                   Show commands without executing
 
+${chalk.bold('PR options:')}
+  --title <title>             Shared PR title (required)
+  --body <text>               Shared PR description
+  --base <name>               Override the base branch for all selected repos
+  --head <name>               Override the head branch (default: current branch)
+  --draft                     Create draft PRs
+  --dry-run                   Show gh pr create commands without executing
+
 ${chalk.bold('Examples:')}
   ${chalk.dim('# Create monorepo from multiple repos')}
   npx unirepo init my-monorepo https://github.com/org/api.git https://github.com/org/web.git
@@ -216,6 +226,9 @@ ${chalk.bold('Examples:')}
   ${chalk.dim('# Pull upstream updates before working')}
   npx unirepo pull
 
+  ${chalk.dim('# Pull one subtree from a specific upstream branch')}
+  npx unirepo pull --prefix api --branch release/2026-04
+
   ${chalk.dim('# Check status')}
   npx unirepo status
 
@@ -224,5 +237,8 @@ ${chalk.bold('Examples:')}
 
   ${chalk.dim('# Push changes upstream')}
   npx unirepo push --dry-run
+
+  ${chalk.dim('# Open PRs for changed subtree repos')}
+  npx unirepo pr --title "feat: add auth flow" --body "Cross-repo auth changes"
 `);
 }