Streamlined install: publish the tilth CLI so users get it without cloning the repo (uvx / uv tool install / binary)

[samkeen]

Motivation

The supported way to get the tilth CLI today is clone-the-repo-and-uv run — installation.md even says so out loud: "the supported install path today is cloning the repo and running it through uv … a packaged install story is on the roadmap, not here." That clone step is the single biggest piece of friction in onboarding, and it's load-bearing in two places:

1. Getting the tool. A user who just wants to try Tilth has to git clone, cd, uv sync, and prefix every invocation with uv run. There's no uvx tilth … (zero-install, ephemeral) and no uv tool install tilth (persistent, run from anywhere).
2. The demo story. running-the-demo.md currently asks the reader to clone two repos — Tilth itself and the demo workspace — then uv run tilth prep-feature … / uv run tilth run … from inside the Tilth clone. Half of that ceremony is just "acquire the tool." Removing the Tilth clone collapses the demo to: get the tool → point it at a workspace.

This issue tracks landing a simple install path for the tilth CLI — the roadmap item the installation page defers to.

Current state

• The package is already shaped for distribution: pyproject.toml declares the entry point tilth = "tilth.cli:main" and a hatchling wheel target (packages = ["tilth"]). So uv tool install --editable . from a clone already works mechanically.
• What's missing is (a) a published artifact so there's nothing to clone, and (b) the runtime-path fixes that let the tool run from outside a clone.

Candidate install paths (not mutually exclusive)

Path	UX	Needs
uvx tilth …	Zero-install, ephemeral — best possible demo opener	Publish to PyPI (or a uv-resolvable index) + path fixes (#8)
uv tool install tilth	Persistent, tilth on PATH from anywhere	Same as above
pipx install tilth	Same shape for the pipx crowd	PyPI publish
Standalone binary (PyInstaller / shiv / pex)	No Python toolchain at all	Build pipeline; heavier; probably overkill if PyPI works
uv tool install --editable . (from clone)	Today's contributor path, no clone-removal	Path fixes (#8) only — already mechanically possible

Recommendation to evaluate first: publish to PyPI → uvx tilth for end users, keep uv sync / uv tool install --editable . documented as the contributor path. uvx is the one that truly removes the clone for the demo. A binary is a fallback if PyPI distribution proves insufficient.

Hard prerequisite

#8 (move sessions/ and .env out of the clone) is a blocker, not an adjacent nicety. With uvx/uv tool install there is no clone at all, so:

• SESSIONS_DIR can't derive from __file__ (it'd land inside the uv tool cache and get wiped on upgrade).
• .env can't be found by walking up from a clone that doesn't exist.

#8 already scopes both fixes (XDG-style data dir + .env search order with $TILTH_ENV_FILE / ~/.config/tilth/.env / CWD fallback). That work lands first; this issue layers the publish/distribution on top.

Demo-story simplification (bullet 2 on the napkin)

Once the tool installs cleanly, running-the-demo.md shrinks. Today:

git clone …/tilth.git && cd tilth && uv sync && cp .env.example .env  # acquire the tool
git clone …/tilth-demo-todo-cli.git ~/projects/tilth-demo            # acquire the workspace
uv run tilth prep-feature ~/projects/tilth-demo
uv run tilth run          ~/projects/tilth-demo

After:

git clone …/tilth-demo-todo-cli.git ~/projects/tilth-demo  # workspace still needs to be a git repo
uvx tilth prep-feature ~/projects/tilth-demo
uvx tilth run          ~/projects/tilth-demo

Note the demo workspace still has to be a real git repo — the worktree machinery requires it, so that clone stays. (Stretch: a tilth init-demo <dir> that scaffolds an empty git repo + AGENTS.md would remove even that clone, but it's out of scope here.)

Checklist / open questions

• Confirm package data ships in the wheel — the runtime reads tilth/prompts/*.md and tilth/seed/ assets at startup; verify hatchling includes non-.py files in the built wheel (a wheel that drops the prompts would install but crash at run time).
• PyPI namespace: is tilth available? If not, decide on the published name (and whether the entry-point command stays tilth).
• Release plumbing: manual uv build + uv publish, or a tagged-release GitHub Action? Version is 0.1.0 today.
• Sequencing against Support uv tool install by moving sessions/ and .env to user-data locations #8 — land path fixes, then a 0.1.x publish, then flip the docs.

Docs impact

• docs/getting-started/installation.md — pivot the lead to uvx / uv tool install; demote clone-and-uv sync to the contributor section; drop the "no packaged install yet" disclaimer.
• docs/getting-started/running-the-demo.md — strip the Tilth clone + uv run prefix from the worked commands.
• README.md quickstart — same pivot.

Related

• Support uv tool install by moving sessions/ and .env to user-data locations #8 — prerequisite. Path resolution for sessions/ and .env so the tool runs from outside a clone.
• validators.py: make the mechanical floor language-pluggable (today: hard-coded ruff + pytest) #20 — orthogonal: decoupling the validator floor from Python tooling (a non-Python user still needs a clean install).