Investigate CLI Repo and Branch Flags · Entire

make a new branch off origin/main for this. i have a feeling that entire trail ... commands all require the cli to be running inside a checked-out git repo, and it derives the trail's repo and branch from that. i'd like to be able to use the cli as a backend for my own Trails GUI, so it could be good to add --repo and --branch flags, too, where appropriate. don't write code yet, investigate feasibility.

I'd like to be able to call, e.g.,

entire trail show --repo gh/entireio/cli --branch my/feature
entire trail finding list --repo gh/entireio/cli --branch my/feature
entire trail finding list --repo gh/entireio/cli --trail-id 123

Let me check runAuthenticatedTrailAPI and the context cache to confirm auth itself doesn't need a git repo.

I have everything I need. Here's the feasibility assessment.

Bottom line

Feasible, and the change is small and localized. Every entire trail command derives the repo from origin and the branch from the current checkout through exactly two chokepoints. Add --repo/--branch overrides at those two points and the read/metadata commands work with no git clone at all. Auth is already git-independent (it keys off the API base URL's .well-known/entire-api.json, exactly as entire activity does — nothing to change there).

The only two git dependencies

1. resolveTrailRemote(ctx) (trail_cmd.go:1633) → gitremote.ResolveRemoteRepo(ctx, "origin") — produces the (forge, owner, repo) triple used to build every API path (/api/v1/trails/<forge>/<owner>/<repo>/...). Requires a clone with an origin remote.
2. GetCurrentBranch(ctx) (git_operations.go:188) — used only when no trail selector is given, to find the trail by branch.

That's it. The triple and branch are passed as plain strings into findTrailByBranch / findTrailBySelector / trailsBasePath — nothing validates them against a local clone. So overriding them is purely additive.

What --repo gh/entireio/cli maps to

gh/entireio/cli is the forge/owner/repo triple verbatim — the server path format. A --repo flag just needs to split on / into 3 segments (and optionally accept a full clone URL via the existing gitremote.ParseURL). No new server contract.

Per-command breakdown

Clean wins (read/metadata only — these should get --repo/--branch):

• trail show, trail list, trail update, trail delete, trail watch
• trail finding + list, add, show, update, resolve, dismiss, reopen

Note on findings + branch:entire trail finding already has a --trail selector that accepts number, id, or branch (trail_review_cmd.go:92). So once --repo exists, --trail my/feature and --trail-id 123 both already work — your --trail-id 123 example maps to the existing --trail 123. You may still want --branch as an explicit, clearer alias.

Inherently local — should NOT get --repo (they mutate the local worktree):

• trail create — creates/fetches/pushes local branches
• trail checkout — checks out a branch in the worktree
• trail finding apply — applies a patch to the worktree and verifies local HEAD (trail_review_cmd.go:1037, :1022)

Recommended seams (when we write code)

• Add --repo as a persistent flag on the trail root (newTrailCmd, trail_cmd.go:41) — same pattern as the existing persistent --insecure-http-auth. Conflict-free; no command defines --repo today.
• Wrap the two chokepoints: a resolveTrailRepo(cmd, ctx) that returns the parsed --repo triple or falls back to resolveTrailRemote(ctx); similarly for branch.
• --branch is trickier: create/update/delete already define a --branch flag with command-specific meaning, so it can't be a single persistent flag. Add --branch per-command on show/finding/watch (which today only use the current branch), and leave the existing three as-is.
• The best-effort enablement cache (currentTrailEnablementScope, trail_context_cache.go:91) reads origin too, but it's debug-log-only on failure — it degrades gracefully outside a clone. Optionally feed it the --repo triple so the cache works in GUI mode, but not required for correctness.

Want me to turn this into an implementation plan (or just build it)?

this sounds reasonable. let's make this feature and see what my colleagues say. as for the --branch flag, yes, let's only add it on the commands where that makes sense.

Done. Committed on trail-repo-branch-flags (not pushed).

What shipped

--repo (persistent on trail root) — accepts gh/entireio/cli or a clone URL; defaults to origin. Honored by show, list, update, delete, watch, finding (+ subcommands). Rejected on the local-clone commands (create, checkout, finding apply) with a clear error.

--branch (new on show, watch, finding) — selects the trail by branch instead of the current checkout. update/delete already had it. Mutually exclusive with an explicit trail selector.

Your examples now work without being in the repo:

entire trail show --repo gh/entireio/cli --branch my/feature
entire trail finding list --repo gh/entireio/cli --branch my/feature
entire trail finding list --repo gh/entireio/cli --trail 123   # --trail already accepts number|id|branch

Design notes for your reviewers

• Two chokepoints, not scattered: every command resolved repo via resolveTrailRemote and branch via GetCurrentBranch. Added resolveTrailRepoOrRemote / resolveTrailBranch wrappers; the override threads through existing options structs/params with no behavior change when flags are absent.
• Auth untouched — already git-independent (.well-known/entire-api.json off the API base URL, same as entire activity), so ENTIRE_API_BASE_URL=https://partial.to picks the right context automatically.
• --trail-id 123 from your example maps to the existing --trail 123.

Verification

• mise run fmt && mise run lint → 0 issues
• Full cmd/entire/cli package tests pass; added trail_repo_flag_test.go (parser table, override-skips-git, mutual-exclusion, local-command guards).

Want me to push, or open a draft PR?

push and open a PR. Reason in the description is to make it easier to use trails as a scripting tool.

retrieve the PR comments from https://github.com/entireio/cli/pull/1532 and the trail finding from https://entire.io/gh/entireio/cli/trails/671/feat-trail-repo-and-branch-overrides - they boil down to the same thing. make the slug parsing stricter and fail clearly.

Yes — it was a valid (low-severity) issue, and it's now fixed.

Verdict on that comment

Real bug: the trails-enablement cache writes all derived the repo from the local origin, ignoring --repo. Running entire trail … --repo gh/other/repo from inside a clone of repo A would record "A is trails-enabled" off a query that never touched A, and the error path would even make a spurious enablement network call about A. (In a non-clone dir it was a harmless no-op.)

Fix (pushed in e30a96559)

Threaded the --repo override into runAuthenticatedTrailAPI and skip the cache writes when it's set — both noteTrailCommandEnablement and watch's explicit saveTrailsEnabledForRepoBestEffort. Checkout passes "" (it rejects --repo, so it always tracks local origin). Replied to the cursor comment with the SHA.