Interactive Wizard for Repo Creation

I've looked at how repo creation works today and what the API accepts. Below is a proposed interactive flow, followed by the decisions I need from you before I write any code.

What creating a repo takes

Today's command: entire repo create <name> --project <ref> [--object-format sha1|sha256] [--no-wait] [--wait-timeout 10m] [--json] (cmd/entire/cli/repo.go:111)

What the API accepts (POST /repos):

Things the API does not accept at creation:

• Visibility. The only way to set it is a second call afterwards, the same one repo edit --visibility makes.
• Branch protection, grants and CI. Each has its own endpoint that runs on an existing repo.

Data the wizard can use:

• Projects: GET /projects lists every project you can access, page by page. Each project carries capabilities.canCreateRepository, region, primaryProcessingCell and repositoryCount, so the picker can show only projects you can create in.
• Clusters: GET /clusters lists each cluster's slug, jurisdiction, public URL and whether it's the default. The mirror wizard already turns this into a picker (availableRegions, repo_mirror_add_wizard.go).
• Creating a project: project create needs a name, owner and region. GET /orgs lists the orgs you could pick as owner.

Code we can reuse:

• The mirror-add wizard pattern: run without arguments and you get the wizard, but only when interactive.CanPromptInteractively() is true.
• uiform.New, and runPromptForm, which shows prompts on stderr.
• The existing spinner and readiness wait (awaitRepoActive), and the result output (reportRepoCreation).

Proposed flow

Non-interactive behaviour stays exactly as it is now: without a TTY, or with --json, a missing name or --project is still an error.

Decisions for you

1. How the wizard starts. I'd suggest: run it only when there are no arguments and a terminal is attached. Alternatively, it could fill in whatever is missing, so entire repo create web would ask only for the project. I lean towards filling in what's missing (or supporting both); either way, --project would stop being a hard requirement when a terminal is attached.
2. Creating a project inside the flow. This helps first-time users, but it adds an owner picker and a region picker. It could be in v1 or left for later.
3. Visibility. Should creation be followed by a visibility call? If that second call fails, the repo already exists, so we'd need a clear "created, but visibility wasn't set" message.
4. Checking the name. We could call ListProjectRepos(name=…) to catch "already exists" before creating, or rely on the server's 409 error and let the user fix the name and retry.
5. Cluster pinning. --cluster isn't a flag today. Should the wizard and a new --cluster flag offer it? It's unclear how a cluster's jurisdiction maps to a project's primaryProcessingCell (one is a region name, the other a cell ID), so filtering the list correctly may need someone on the backend to confirm.
6. Object format. Show it under "advanced", or leave it out of the wizard and keep only the flag?
7. After creation. Offer to add the new repo as a git remote in the current repo, just print the commands, or do nothing?
8. Help classification. New commands must be classified for entire agent-help (a product call). This isn't a new command, but its help text will change to describe the wizard.

My recommendation for v1: fill in missing values, no project creation, advanced options folded away, visibility included, and the git-remote offer at the end. Tell me which way you want to go on each point and I'll turn it into a final spec before implementing.

To answer your question 3: yes, it really can't be set at creation. POST /repos accepts only name, projectId, objectFormat and clusterHost. The only way to set visibility is PUT /repos/{id}/visibility after the repo exists, which is what repo edit --visibility calls. The create response does include the repo's visibility, so we can show the default. The spec doesn't document what that default is, though I'd expect private.

That leaves two options for the wizard:

• (a) Ask for visibility, create the repo, then set it. If the second call fails, the repo still exists and we print entire repo edit … --visibility … so you can finish.
• (b) Leave visibility out of the wizard and show the default in the summary. Changing it stays a separate repo edit.

I'd go with (a), and add a matching --visibility flag to repo create so the wizard and flags stay consistent.

On your answer 5: no change is needed. The CLI never sends clusterHost, so the server already uses the project's cluster. The wizard won't show it.

Draft spec: entire repo create interactive mode

When the wizard runs

• It runs only when both of these are true:
  • a terminal is attached (interactive.CanPromptInteractively());
  • at least one required value is missing (the <name> argument or --project).
• If both required values are given, the command behaves exactly as it does today: no wizard and no summary.
• Without a terminal and with a required value missing, it fails with the same error as today.
• --json still prints only JSON on stdout, and the prompts go to stderr.
• Every value given as an argument or flag is pre-filled as that step's default, and you can still change it:
  • <name>
  • --project
  • --object-format
  • --visibility, if we add it
• If --project doesn't match a project, the command fails immediately with today's error rather than silently switching to the picker.

Steps. Each answered step stays on screen as a recap line, e.g. ✓ Project acme, so you can see every choice made so far.

1. Project: a filterable list showing only projects where you're allowed to create repos, e.g. acme · 12 repos · us.
   • A --project value is pre-selected.
   • If you have exactly one eligible project, it's still shown, pre-selected.
   • If you have none, the command stops with a hint to run entire project create.
2. Name: a text input.
   • When you submit, it checks the allowed characters and length (1–64 characters from [A-Za-z0-9.-], starting and ending with a letter or digit).
   • Then it looks up the name in the chosen project and rejects it if it's taken.
   • If the server still returns a 409 at creation time, the wizard comes back to this step.
3. Visibility: private (default) or public. This depends on option (a).
4. Advanced options? A yes/no question, defaulting to No.
   • Yes asks for the object format: sha1 (default) or sha256, with a note that sha256 is less widely supported by git tools.
   • No shows server default (sha1) in the summary.
5. Summary: a card listing project, name, visibility and object format, then Create, Edit or Cancel.
   • Edit lets you pick which field to change and returns to the summary afterwards.
   • Cancel exits cleanly and creates nothing.

Creating and the result

• There's a spinner while the repo is provisioned. It reuses the existing readiness wait, so --no-wait and --wait-timeout behave as they do now.
• If you chose a visibility, it's set next.
• The output is today's ✓ Created repository … block (ID, state, Remote: entire://…), followed by:
• If creation succeeds but provisioning isn't confirmed as ready, the error path is the same as today: the repo's details are kept and we say not to create it again.

Help and agent guidance

• Long and the examples get a wizard example, and --project is no longer marked as a hard requirement.
• The agentHelpClassification entry stays as it is. Agents should keep passing both values as flags, which never triggers the wizard.

Testing

• Unit tests cover:
  • when the wizard runs, and when it doesn't;
  • pre-filled values from arguments and flags;
  • the name check;
  • building the summary and the Edit loop;
  • the next-steps output;
  • the visibility call failing after a successful create.
• The existing non-interactive tests must pass unchanged.

Still open

1. Visibility: option (a) with a new --visibility flag, or option (b)?
2. Should Edit on the summary pick a field (my proposal) or go back through all the steps?
3. If a --project value doesn't resolve, should it fail immediately (my proposal) or fall back to the picker with a warning?

Once you've answered these, I'll implement it following the mirror-add wizard's structure.

entire repo create now opens the wizard you specced when a terminal is attached and the name or --project is missing. Nothing is committed yet. Its tests pass, lint is clean, and the canary passes. mise run check failed on one test, TestPlugin_SpawnsHooksUnderNode in agent/opencode, because my local mise has no Node version set; that has nothing to do with this change.

How the wizard behaves:

• Step order: project, then name, then visibility, then "Customize advanced options?" (object format behind it), then a review with Create, Edit or Cancel.
  • Each answered step stays on screen as a line like ✓ Project acme.
  • Edit goes back through every step, starting from your previous answers.
  • Cancel exits 0 and creates nothing.
• Project picker: it only lists projects you're allowed to create repos in, sorted by name, e.g. acme — acme-inc · us · 3 repos.
• Defaults from flags: anything passed as an argument or flag pre-fills its step. If you passed --object-format, the advanced question defaults to Yes.
• Bad --project: if it doesn't exist, or you can't create repos in it, the command fails before the first prompt.
• Name check: a name already taken in the project is rejected and asked again. If the create still gets a 409 (someone took the name in the meantime), you go back through the steps.
• No terminal: a missing name or --project is refused before any network call, and the error shows the full command. The one-shot path otherwise behaves as before.
• Visibility: new --visibility public|private flag, default private in the wizard. It's a second call after the create, skipped when the create already reports the value you asked for. If that call fails, the repo is kept, you get the entire repo edit … --visibility … command to finish, and the exit code is nonzero.
• After creating: it prints three commands — clone, add as a remote, and mirror:

Choices I made that you may want to revisit:

• Next steps in one-shot runs too: they also print in normal non-interactive output, not just the wizard. They're left out of --json, after any error, and when the /et/… path can't be worked out.
• Name validation is minimal: only empty, / and spaces are rejected. Stricter client-side rules previously made the CLI refuse names the API and web app accept (COR-1891), so the server stays the judge.
• Wizard time doesn't count against --wait-timeout: the timeout bounds the lookups before the first prompt, and separately the create and readiness wait. The help text says so.
• Agent-help classification is unchanged: repo is already classified as user-owned, and agents passing both values never trigger the wizard.

Not verified: I tested the wizard by scripting answers in accessibility mode (ACCESSIBLE=1), not in the full interactive terminal UI. It's worth running entire repo create once yourself to see the styled version.

The code is in cmd/entire/cli/repo_create.go (shared create logic, visibility, next steps) and repo_create_wizard.go, with the flag and help changes in repo.go and tests in repo_create_test.go. I also added a short note to docs/development/cli-conventions.md.

The peer session (the one that built the project create wizard in PR #2618) sent the design to follow, and repo create now looks and behaves like that wizard. As you approved, this branch is stacked on #2618, so it has to land after it. Nothing is committed. Lint is clean, unit, integration and canary tests pass, and I drove the real binary in a terminal emulator in both the styled and accessible modes.

Changes from the version you saw:

• One paged form: Project → Name → Visibility → Advanced → Object format (only shown if you said yes to Advanced) → Summary. Each page lists your earlier answers, dimmed, above its heading.
• Going back: instead of an Edit button, Shift+Tab walks back through every page, and the summary says so. It still meets your "go back through all steps" answer, but check you're happy with that change.
• Defaults: anything passed as an argument or flag is only the starting value, and every page still shows. With no name given, it suggests the current git folder's name.
• Project picker: only projects you can create repos in, sorted by name, with a "N projects hidden" note.
• Name check on the page: a taken name is rejected as you press Enter. Each project's repo names load in the background when you pick it. If the server still reports the name as taken at create time, the wizard reopens with a note.
• Summary: shows every value plus the equivalent one-line command (e.g. entire repo create web --project acme --visibility private), then Create or Cancel.
• No ULIDs in the output: the success line reads ✓ Created repository acme/web, and recovery commands use /et/acme/web. The ID appears only when no path is known, and in the "contact support" line.
• Accessible mode (ACCESSIBLE=1): notes go into the question text because huh drops descriptions there, and Enter keeps a pre-selected project (the peer found that gap).

A huh bug found in the real-terminal run: type an invalid or taken name, press Enter, then Shift+Tab, and the page freezes; only Ctrl+C gets out. This is in huh itself (v2.0.3, the latest). I added a small workaround in cmd/entire/cli/uiform/backnav.go: validation steps aside only while the key is Shift+Tab, so going back works and Enter still checks. project create has the same bug. I've told the peer and offered to move the helper into their PR.

Your call: the helpers now shared by both wizards (currentFolderName, wizardLoginNote, the dimmed recap style) live in the project wizard's file. Fine while the PRs are stacked, but they could move to a shared file later.

The wizard is in cmd/entire/cli/repo_create_wizard.go and the shared create logic in repo_create.go. The success and recovery wording changed in repo_readiness.go, and docs/development/cli-conventions.md is updated.

The Shift+Tab workaround (uiform/backnav.go) now comes from the peer's PR instead of this branch. The peer copied the files unchanged: I checked both are identical, deleted mine, and moved this branch forward to their latest commit (3ad5f288f). They've fixed the same freeze on the project create name page.

The peer warned that huh's WithProgramOptions overwrites the form's input and output settings if it's called after runPromptForm. My wizard already calls it first (repo_create_wizard.go:394, before line 396), so nothing is lost.

Build, the repo create/project create tests and lint all pass after the move. My work is still uncommitted on top of their branch, and this PR still has to land after #2618.

The Using context 'eu.auth.partial.to'. line is gone from the repo create project page. The wizard still suppresses the notice that would otherwise print above the form, so the active login isn't shown anywhere while it runs. Tests and lint pass.

project create still shows the same line on its owner page. That code belongs to the peer session's PR, so I haven't touched it. Should I ask them to remove it there too, so the two wizards stay consistent?

The next steps now point origin at the new repo with --override, and the wording shows that cloning and repointing are alternatives:

--override is safe to copy either way. If the checkout has no origin, it adds one. If it has one, the command repoints it and prints the URL it replaced.

Tests and lint pass.

I pushed the branch and opened PR #2628: https://github.com/entireio/cli/pull/2628

It's stacked on the project create wizard PR (#2618), so its base is add-create-project-interactive and it shows only the repo create commit. After #2618 merges, retarget it to main.

• Pre-commit check: mise run check failed only on TestPlugin_SpawnsHooksUnderNode in agent/opencode. That's the same local problem as before (mise has no Node version set), in code this PR doesn't touch; lint, unit and integration tests passed. I committed anyway and said so in the PR description.
• Trail findings: I couldn't check them. entire trail finding list 2628 returned "repository not found (404)" under the eu.auth.partial.to login, and entire agent-help trail says trails aren't enabled for this repo. You'll need to check the PR's review findings yourself, or tell me which login to use.

The trail for PR #2628 is #1454. It's reachable with the saved us.auth.entire.io login; entire.io on its own isn't a saved login name, so the command refused it.

The review is still running and has no findings so far. I'm polling in the background and will go through the findings once it finishes.

I went through all the review comments on PR #2628, fixed or answered each, and marked every conversation resolved: five from Copilot and one from Cursor Bugbot that arrived meanwhile. The fixes are pushed in two commits, ac671765c and fe9562f46. Each fix has a regression test that fails without it. Lint, unit and integration tests pass; mise run check still fails only on the Node-setup test in agent/opencode.

Fixed:

1. Unquoted repo path in printed commands: the path is now shell-quoted in the repo edit --visibility hint, the readiness recovery lines and the next steps. A normal path like /et/acme/web prints unchanged.
2. Help showed create <name> [<name>]: it now reads create [<name>].
3. Visibility lost after the readiness wait: if the readiness response left out visibility, the command sent an unneeded second request and could report a false failure. The create response's visibility and fullName are now kept when the readiness response omits them.
4. Stale "name was taken" note: the note now shows only while the project where the name was refused is selected.
5. Visibility skipped after a wait timeout (Cursor): it was run on the context --wait-timeout had already expired, so it never happened. When the deadline ends the wait, it now gets its own 30-second budget. Ctrl+C still stops it.

Answered without changing behaviour: 6. Projects with no permissions field are still offered: Copilot wanted them hidden. I kept them, matching the project create wizard (#2618), where the server decides. The spec requires that field, so only a misbehaving server leaves it out, and hiding those would empty the picker on such a server. I corrected the docs and the PR description, which had overstated the filter.

I also updated the PR description to cover the visibility-after-timeout change.

The Entire trail review (#1454) restarted after the push. It has no findings so far, and my background check will report once it finishes.

I went through another session's review of trail #1454 (items 1–5 below) and pushed fixes to PR #2628 as a13ff2bb9. Each fix has a new test. mise run check passes except the same Node-setup test in agent/opencode.

Fixed:

1. --json opened the wizard in a terminal. With a missing name or --project, --json is now refused like a run without a terminal, before any request. A script running under a pseudo-terminal can no longer hang on the form.
2. Visibility was set even when provisioning failed. It's now skipped if the wait failed for any reason other than timing out: provisioning failed, readiness couldn't be read, or Ctrl+C. The command prints how to set it once the repo is active instead of adding a second error. Success, --no-wait and the timeout path behave as before.

Kept, with reasons sent back to the reviewer: 3. --project help says "(by name)" though ULIDs still work. This is intentional under the #2618 design: ULIDs are still accepted, but help and examples don't mention them. project create --owner does the same. 4. The summary shows "sha1 (server default)". The API spec itself documents sha1 as the default, and the summary is meant to show what the repo will actually get. 5. Every 409 is treated as a name clash. The spec documents the create endpoint's 409 only as a generic "Conflict", so it can't be narrowed reliably. The wizard still reopens, but now shows the server's own reason instead of saying the name was taken.

Cross-wizard: project create has the same --json problem (point 1). I've told the session that owns #2618.

Checked after pushing: there are no open review threads on GitHub. The trail review restarted with the push and has no findings yet. My first background poll hit its time limit before the review finished, so I've started a new one that runs for up to 10 minutes, and I'll handle any findings it turns up.

The latest review round has turned up nothing new so far, but the trail review isn't finished. Nine minutes after my last push, trail #1454 is still "reviewing" and has no findings. My 10-minute background check ended before the review did. GitHub has no unresolved review threads on PR #2628.

Nothing is waiting on me. When the review finishes, run entire trail finding list 1454 --context us.auth.entire.io, or ask me to check it again.

repo create prompts again under --json when it runs in a terminal, matching project create. Pushed to PR #2628 as 30b75e6ca.

The session that owns project create said you chose to keep prompting under --json; that came through them, not from you here. It matches the grant add convention: the form draws on stderr or the terminal, and stdout carries only the JSON, so entire repo create --json | jq still works. Without a terminal (CI, pipes) a run missing the name or --project is still refused before any request.

• Partial revert: I undid only the --json gating from a13ff2bb9. The same commit also stops setting visibility when provisioning fails, and shows the server's reason when a create is refused as a conflict. Both are separate review fixes, so I kept them.
• Test: TestRepoCreateWizard_UnderJSONPrintsOnlyTheObject runs the wizard with --json and checks that stdout parses as the repo JSON and nothing else.
• Docs: the help text and cli-conventions.md now describe this.
• Checks: mise run check passes except the same local Node-setup failure in agent/opencode.
• Reviewer: I told the session that reviewed trail #1454 why its first item is reverted; its other fixes stay in.

repo create now trims spaces around the name argument before either path, so entire repo create " web " --project acme creates web, the same name the wizard would. This matches the peer's fix in project create, and I've told that session it's done. Pushed to PR #2628 as 5b5e08fad.

• Blank names: an all-blank name now counts as missing. In a terminal the wizard opens; otherwise the command is refused before any request.
• Other names: only surrounding spaces are removed, so a name like web.git still reaches the server as typed.
• Test: TestRepoCreate_NameArgumentIsTrimmed covers both cases.
• Checks: mise run check passes except the same local Node-setup failure in agent/opencode.

The peer's project create branch (#2618, which this PR builds on) has commits this branch doesn't include yet, such as their own name-trim fix. That's fine until #2618 merges. After that, bring this branch up to date: a merge avoids a force-push, a rebase would need one. I can do either when you say.

No change needed here. The peer fixed their project create duplicate-name check, because project names are unique across all owners and they had only checked the chosen owner's projects. Repo names work differently: they only need to be unique within their project. Two code comments say so (resolveref.go:293, repo.go:522), and the server's lookup by repo name is scoped to a project.

The repo create wizard checks the new name against the chosen project's repos only, which matches that scope. I've told the peer.

repo create now follows the new rule, so flags no longer pre-fill the wizard. It's pushed to PR #2628 as 8ba65ee05, and mise run check passes except the same local Node-setup failure in agent/opencode.

--no-wait, --wait-timeout and --json don't count as create flags, so they still work with the wizard; under --json stdout carries only the repo JSON.

I removed the code that matched --project against the picker and pre-filled visibility and object format from flags. Two new tests pin the behaviour: TestRepoCreate_FlagsMeanTheFlagForm (refusal with zero requests) and TestNewRepoCreateState_TakesOnlyTheName. I also updated the help text, cli-conventions.md and the PR description, and told the project create session.

The project create session has pushed its matching change. Nothing in it affects this branch, so I haven't merged it in; I'll update this branch from theirs once #2618 merges.

No change needed. The project create session found that --owner "" still opened its wizard, because it checked whether a flag had a value rather than whether it was passed. repo create checks whether the flag was passed (repo_create.go:65), so --project "" still counts as the flag form and is refused.

TestRepoCreate_FlagsMeanTheFlagForm already covers repo create web --project "", asserting the refusal and zero requests. I've told the peer.

I worked through the re-review of trail #1454 and pushed 37c77f536. It merges the base branch (#2618) into this one and includes the fixes, so PR #2628 now has no conflicts and CI is running on it. mise run check passes except the same local Node-setup failure in agent/opencode.

1. Merge conflict: main added a refusal for repo names ending in .git, which reverses the earlier rule that such names go through. I kept it. It now runs on the trimmed name before either path, and the wizard's name page refuses the same names, suggesting the spelling to use (web.git → web). New tests cover both: a refused name makes no request and never opens the wizard.
2. Conflict note: when the server refuses a create as a conflict, the note no longer insists on another name. It shows the server's reason and says to change the name or the project, or cancel.
3. Refusal order: with no terminal, the missing-input error now comes first. Before, entire repo create --project acme in CI got the flag-form error suggesting you run without flags to be prompted, which can't work there.
4. Wording: fixed the help sentence and the cli-conventions.md line the reviewer flagged.

I've sent the reviewer a point-by-point reply. A background job is watching CI and the trail. CI and the trail review haven't reported on the new commit yet; I'll handle anything they turn up.

Resolved. Watching the new head's CI and the trail re-review in the background.