outrider CLI: --bulk-repos, --no-cron on setup-local, install-paths docs (REMYX-147) (#43)

Three CLI improvements driven by Wave 1-3 onboarding pain:

- `--bulk-repos PATH` on `outrider init` + `outrider setup-local`: a
  TSV-driven loop (`owner/name<TAB>uuid` per row). Per-row errors are
  captured and reported in a summary at the end — one failure does not
  abort the remaining rows. `--pace SECONDS` tunes inter-row spacing
  (default 3s). Mutually exclusive with --repo / --interest /
  --auto-interest.

- `--no-cron` on `setup-local`: workflow renders with the schedule
  block commented-out (not removed). Re-enable later by uncommenting
  three lines — no need to re-run setup-local. Engine-side `init
  --no-cron` is not yet wired; deferred to a follow-up that needs
  engine cooperation.

- New docs/install-paths.md covers init vs setup-local trade-offs,
  the App-install dependency (and what happens if you write the
  workflow manually), `--no-cron`, and the `--bulk-repos` workflow.
  README gets a one-sentence pointer to the doc.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: smellslikeml

README.md

@@ -134,6 +134,8 @@ Once Outrider is installed, `remyxai outrider trigger` dispatches an ad-hoc run
 
 If the Remyx GitHub App isn't installed on the target repo yet, the command surfaces the install link.
 
+For the no-App `setup-local` path, the `--no-cron` switch, and `--bulk-repos` onboarding across many repos at once, see [docs/install-paths.md](docs/install-paths.md).
+
 ## Command reference
 
 Run any command with `--help` for full flag listings and examples.

docs/install-paths.md

@@ -0,0 +1,83 @@
+---
+type: howto
+description: Two paths to install Outrider on a repo, when to use each, and how to onboard many repos at once.
+tags: [outrider, install, github-app, setup-local, bulk-repos]
+---
+
+# Installing Outrider on a repo
+
+There are two CLI paths to install Outrider on a target repo, plus a bulk path for onboarding many repos in one shot.
+
+
+## `outrider init` — the default
+
+Drives the Remyx engine to register the **Remyx GitHub App** (`remyx-ai[bot]`) on the target, write the workflow, set the repo's Actions secrets, and open a bot-authored setup PR. In `auto` mode it also merges the PR and fires the first run.
+
+```bash
+remyxai outrider init --repo owner/name --auto-interest
+```
+
+The App is the load-bearing piece. At runtime, the workflow asks the engine to mint a short-lived `remyx-ai[bot]` token so the action's PRs and Issues are authored by the bot — not `github-actions[bot]`. **Without the App installed on the target, that token-mint silently returns empty and the action falls back to the workflow's built-in `GITHUB_TOKEN`** — the run still succeeds but the artifacts are anonymous and skip the convention-pass enrichments that key off the bot author. Always prefer this path when the org can grant the App.
+
+If the App isn't installed yet, the command surfaces the install link — accept it once and the engine handles the rest.
+
+
+## `outrider setup-local` — when the App can't be granted
+
+For enterprises that can't grant a third-party App yet (pending security review, restricted org policy):
+
+```bash
+remyxai outrider setup-local --repo owner/name --auto-interest
+```
+
+Uses your own authenticated `gh` CLI to set the repo secrets, write the workflow, and (in `auto` mode) merge the setup PR. No Remyx App, nothing new to security-review. The only Remyx dependency is the `REMYX_API_KEY` the workflow uses at runtime.
+
+The action then opens its PRs / Issues with the repo's built-in `GITHUB_TOKEN` (authored by `github-actions[bot]` rather than `remyx-ai[bot]`).
+
+### `--no-cron`
+
+By default the workflow ships with a scheduled cron at 14:00 UTC Mondays. For trials, cost control, or any "I'll dispatch manually" use case:
+
+```bash
+remyxai outrider setup-local --repo owner/name --interest <uuid> --no-cron
+```
+
+The schedule block is rendered commented-out (not removed entirely), so re-enabling later means uncommenting three lines — no need to re-run setup-local.
+
+Engine-side `outrider init --no-cron` is not yet supported; for now, prefer `setup-local --no-cron` if you need that knob.
+
+
+## Don't write the workflow file manually
+
+Committing `.github/workflows/outrider.yml` by hand (without one of the two CLI paths above) skips the App-install / secrets-set steps. The action will deploy and run, but:
+
+- The bot-token mint silently fails → PRs are `github-actions[bot]`-authored
+- The `REMYX_API_KEY` / `ANTHROPIC_API_KEY` Actions secrets must be set manually
+
+If you've already done this and your runs are producing 0 artifacts, run `remyxai outrider init --repo owner/name --interest <uuid>` after the fact — it's idempotent for the secrets-set step and surfaces the App install link if needed.
+
+
+## `--bulk-repos` — many repos in one shot
+
+Onboarding a portfolio of forks or installing across a team's repos:
+
+```bash
+remyxai outrider init --bulk-repos repos.tsv --mode review --yes
+```
+
+`repos.tsv` is a tab-separated mapping of repo → ResearchInterest UUID, one per line. Blank lines and `#`-prefixed comments are allowed:
+
+```
+# wave-1 forks
+smellslikeml/agents	649828cc-11ec-4ce5-9549-303d1da6f1ce
+smellslikeml/helicone	734a06d2-84c0-4b3f-bb5f-d0ab476b36a9
+
+# wave-2
+smellslikeml/promptfoo	3ede9f1b-ac4b-4468-9718-7314acd85fce
+```
+
+Per-repo errors are captured and reported at the end — one failure does not abort the remaining rows. Use `--pace SECONDS` to tune the inter-repo pacing (default 3s).
+
+`--bulk-repos` is also supported on `setup-local` with the same TSV format.
+
+`--bulk-repos` is mutually exclusive with `--repo` / `--interest` / `--auto-interest` (the TSV is the source of truth for the per-row pair).

remyxai/cli/commands.py

@@ -25,6 +25,8 @@
     handle_interests_toggle,
 )
 from remyxai.cli.outrider_actions import (
+    _parse_bulk_repos_tsv,
+    _run_bulk,
     handle_outrider_init,
     handle_outrider_trigger,
 )
@@ -595,13 +597,22 @@ def outrider():
                   "Don't block polling for the App install or provisioning to "
                   "finish; print next steps and return."
               ))
+@click.option("--bulk-repos", "bulk_repos", type=click.Path(), default=None,
+              help=(
+                  "Path to a TSV mapping repos to ResearchInterest UUIDs "
+                  "(\"owner/name<TAB>uuid\"). Loops `init` over each row "
+                  "sequentially. Mutually exclusive with --repo / --interest "
+                  "/ --auto-interest."
+              ))
+@click.option("--pace", "pace_s", type=int, default=3, show_default=True,
+              help="Seconds to wait between repos in --bulk-repos mode.")
 @click.option("--dry-run", is_flag=True, default=False,
               help="Print the plan and exit without making any changes.")
 @click.option("--yes", "-y", "skip_confirm", is_flag=True, default=False,
               help="Skip the confirmation prompt (default is opt-in).")
 def outrider_init(
     repo, interest_id, auto_interest, mode, anthropic_key,
-    no_wait, dry_run, skip_confirm,
+    no_wait, bulk_repos, pace_s, dry_run, skip_confirm,
 ):
     """
     Set up Outrider on a GitHub repo.
@@ -623,7 +634,30 @@ def outrider_init(
       remyxai outrider init --repo remyxai/RepoRanger --auto-interest
 
       remyxai outrider init --repo owner/name --interest <uuid> --mode review
-    """
+
+      remyxai outrider init --bulk-repos repos.tsv --mode review --yes
+    """
+    if bulk_repos:
+        if repo or interest_id or auto_interest:
+            raise click.UsageError(
+                "--bulk-repos is mutually exclusive with "
+                "--repo / --interest / --auto-interest."
+            )
+        rows = _parse_bulk_repos_tsv(bulk_repos)
+        _run_bulk(
+            handle_outrider_init,
+            rows,
+            common_kwargs=dict(
+                auto_interest=False,
+                mode=mode,
+                anthropic_key=anthropic_key,
+                skip_confirm=skip_confirm,
+                dry_run=dry_run,
+                no_wait=no_wait,
+            ),
+            pace_s=pace_s,
+        )
+        return
     handle_outrider_init(
         repo=repo,
         interest_id=interest_id,
@@ -652,13 +686,29 @@ def outrider_init(
 @click.option("--anthropic-key", "anthropic_key", default=None,
               help="Anthropic API key to set as the ANTHROPIC_API_KEY repo "
                    "secret. Falls back to $ANTHROPIC_API_KEY, then prompts.")
+@click.option("--no-cron", "no_cron", is_flag=True, default=False,
+              help=(
+                  "Render the workflow with the scheduled cron commented "
+                  "out. Manual `workflow_dispatch` / `remyxai outrider "
+                  "trigger` only. Re-enable later by uncommenting the "
+                  "schedule block."
+              ))
+@click.option("--bulk-repos", "bulk_repos", type=click.Path(), default=None,
+              help=(
+                  "Path to a TSV mapping repos to ResearchInterest UUIDs "
+                  "(\"owner/name<TAB>uuid\"). Loops `setup-local` over each "
+                  "row sequentially. Mutually exclusive with --repo / "
+                  "--interest / --auto-interest."
+              ))
+@click.option("--pace", "pace_s", type=int, default=3, show_default=True,
+              help="Seconds to wait between repos in --bulk-repos mode.")
 @click.option("--dry-run", is_flag=True, default=False,
               help="Print the plan + rendered workflow and exit; no changes.")
 @click.option("--yes", "-y", "skip_confirm", is_flag=True, default=False,
               help="Skip the confirmation prompt (default is opt-in).")
 def outrider_setup_local(
     repo, interest_id, auto_interest, mode, anthropic_key,
-    dry_run, skip_confirm,
+    no_cron, bulk_repos, pace_s, dry_run, skip_confirm,
 ):
     """
     Set up Outrider WITHOUT the Remyx GitHub App.
@@ -681,7 +731,31 @@ def outrider_setup_local(
 
       remyxai outrider setup-local --repo owner/name --interest <uuid> \\
         --mode review
-    """
+
+      remyxai outrider setup-local --bulk-repos repos.tsv --mode review --yes \\
+        --no-cron
+    """
+    if bulk_repos:
+        if repo or interest_id or auto_interest:
+            raise click.UsageError(
+                "--bulk-repos is mutually exclusive with "
+                "--repo / --interest / --auto-interest."
+            )
+        rows = _parse_bulk_repos_tsv(bulk_repos)
+        _run_bulk(
+            handle_outrider_setup_local,
+            rows,
+            common_kwargs=dict(
+                auto_interest=False,
+                mode=mode,
+                anthropic_key=anthropic_key,
+                skip_confirm=skip_confirm,
+                dry_run=dry_run,
+                no_cron=no_cron,
+            ),
+            pace_s=pace_s,
+        )
+        return
     handle_outrider_setup_local(
         repo=repo,
         interest_id=interest_id,
@@ -690,6 +764,7 @@ def outrider_setup_local(
         anthropic_key=anthropic_key,
         skip_confirm=skip_confirm,
         dry_run=dry_run,
+        no_cron=no_cron,
     )
 
 

remyxai/cli/outrider_actions.py

@@ -391,6 +391,103 @@ def handle_outrider_init(
         )
 
 
+# ─── bulk-repos onboarding ────────────────────────────────────────────────
+
+def _parse_bulk_repos_tsv(path: str) -> list:
+    """Read a TSV mapping repos to ResearchInterest UUIDs.
+
+    Format: one row per repo, two tab-separated columns:
+
+        owner/name<TAB>interest-uuid
+
+    Blank lines and ``#``-prefixed comments are skipped. Lines with the
+    wrong column count or a malformed UUID are surfaced with their line
+    number so the caller can fix-then-retry without partial state.
+
+    Returns: list of ``(repo, interest_uuid)`` tuples in file order.
+    """
+    if not os.path.exists(path):
+        raise click.UsageError(f"--bulk-repos file not found: {path}")
+    rows = []
+    errors = []
+    with open(path) as fh:
+        for line_no, raw in enumerate(fh, start=1):
+            line = raw.rstrip("\n").rstrip("\r")
+            stripped = line.strip()
+            if not stripped or stripped.startswith("#"):
+                continue
+            parts = line.split("\t")
+            if len(parts) != 2:
+                errors.append(
+                    f"line {line_no}: expected 2 tab-separated columns "
+                    f"(repo<TAB>interest_uuid), got {len(parts)}: {line!r}"
+                )
+                continue
+            repo_raw, uuid_raw = parts[0].strip(), parts[1].strip()
+            repo = _normalize_repo(repo_raw)
+            if not repo:
+                errors.append(
+                    f"line {line_no}: not a valid GitHub repo: {repo_raw!r}"
+                )
+                continue
+            if not UUID_RE.match(uuid_raw):
+                errors.append(
+                    f"line {line_no}: not a valid UUID: {uuid_raw!r}"
+                )
+                continue
+            rows.append((repo, uuid_raw))
+    if errors:
+        raise click.UsageError(
+            "--bulk-repos parse errors:\n  " + "\n  ".join(errors)
+        )
+    if not rows:
+        raise click.UsageError(
+            f"--bulk-repos file {path!r} contains no installable rows."
+        )
+    return rows
+
+
+def _run_bulk(
+    handler, rows, common_kwargs, pace_s=3,
+    echo=click.echo,
+):
+    """Run ``handler(repo=..., interest_id=..., **common_kwargs)`` per row.
+
+    Per-row exceptions are captured and reported in a summary at the end —
+    one failure does not abort the remaining rows, since the most common
+    error class (an already-installed fork, a permission edge case) is
+    independent across repos.
+
+    Returns: list of ``(repo, status)`` tuples where status is ``"ok"`` or
+    the exception message. Caller can post-filter for retry.
+    """
+    import time
+
+    results = []
+    for i, (repo, uuid) in enumerate(rows, start=1):
+        echo(f"\n── [{i}/{len(rows)}] {repo} ──")
+        try:
+            handler(repo=repo, interest_id=uuid, **common_kwargs)
+            results.append((repo, "ok"))
+        except click.ClickException as e:
+            echo(f"  ✗ {e.message}")
+            results.append((repo, e.message))
+        except Exception as e:
+            echo(f"  ✗ {type(e).__name__}: {e}")
+            results.append((repo, f"{type(e).__name__}: {e}"))
+        if i < len(rows) and pace_s > 0:
+            time.sleep(pace_s)
+
+    # Summary
+    ok = [r for r, s in results if s == "ok"]
+    failed = [(r, s) for r, s in results if s != "ok"]
+    echo("")
+    click.secho(f"== summary: {len(ok)}/{len(rows)} ok ==", bold=True)
+    for repo, msg in failed:
+        echo(f"  ✗ {repo}: {msg}")
+    return results
+
+
 # ─── outrider trigger ─────────────────────────────────────────────────────
 
 WORKFLOW_FILENAME = "outrider.yml"

remyxai/cli/outrider_local.py

@@ -205,9 +205,23 @@ def _gh_dispatch(repo: str, branch: str) -> bool:
 
 # ─── workflow rendering (inline; no Remyx App / bot-token step) ─────────────
 
-def _render_local_workflow(interest_id: str) -> str:
+def _render_local_workflow(interest_id: str, no_cron: bool = False) -> str:
     # No github-token input → the action uses this repo's built-in
     # GITHUB_TOKEN, which setup-local authorizes to open PRs.
+    #
+    # When ``no_cron=True``, the schedule block is rendered commented-out
+    # (not omitted) so the user can re-enable scheduled runs later by
+    # uncommenting three lines, without re-running setup-local.
+    if no_cron:
+        schedule_block = (
+            "  # schedule:\n"
+            "  #   - cron: '0 14 * * 1'   # Mondays 14:00 UTC; uncomment to enable\n"
+        )
+    else:
+        schedule_block = (
+            "  schedule:\n"
+            "    - cron: '0 14 * * 1'   # Mondays 14:00 UTC; pick any cadence\n"
+        )
     return f"""name: Outrider
 
 # Generated by `remyxai outrider setup-local` (no Remyx GitHub App).
@@ -216,9 +230,7 @@ def _render_local_workflow(interest_id: str) -> str:
 #   https://github.com/remyxai/outrider
 
 on:
-  schedule:
-    - cron: '0 14 * * 1'   # Mondays 14:00 UTC; pick any cadence
-  workflow_dispatch:
+{schedule_block}  workflow_dispatch:
 
 jobs:
   recommend:
@@ -246,7 +258,7 @@ def _render_local_workflow(interest_id: str) -> str:
 
 def handle_outrider_setup_local(
     repo, interest_id, auto_interest, mode,
-    anthropic_key, skip_confirm, dry_run,
+    anthropic_key, skip_confirm, dry_run, no_cron=False,
 ):
     """Self-provision Outrider with the user's own gh token (no Remyx App)."""
     import os
@@ -293,7 +305,7 @@ def handle_outrider_setup_local(
 
     if dry_run:
         click.echo("--- rendered workflow ---")
-        click.echo(_render_local_workflow("<interest-id>"))
+        click.echo(_render_local_workflow("<interest-id>", no_cron=no_cron))
         click.secho("dry-run: no changes made.", fg="yellow")
         return
 
@@ -333,7 +345,7 @@ def handle_outrider_setup_local(
         branch_created = True
         click.echo(f"✓ Created branch {branch_name}")
 
-        workflow = _render_local_workflow(resolved_interest)
+        workflow = _render_local_workflow(resolved_interest, no_cron=no_cron)
         _gh_put_file(resolved_repo, branch_name, WORKFLOW_PATH, workflow,
                      "Install Outrider (self-provisioned via remyxai CLI)")
         click.echo(f"✓ Wrote {WORKFLOW_PATH}")