> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # Repairing projects Use `tessl project repair` when Tessl detects that the project identity for your current repository no longer matches the project it is linked to. A Tessl project has two parts of identity: - its **locator** — the project name in `tessl.json` - its **source** — the repository Tessl sees for the current directory If those drift apart, Tessl can stop evals from running until you repair the association. ### What `tessl project repair` does `tessl project repair` helps you diagnose and fix **project identity drift** for the current repository. Depending on the problem, you can use it to: - inspect the current mismatch - **relink** this repository to a different existing Tessl project - **update the source** recorded for the currently matched Tessl project - **update the project name** to match a local rename ### Start by diagnosing Run this first: ```bash tessl project repair ``` This checks the current repository and shows whether the problem is: - a **locator drift** - a **source drift** - a **rename drift** - a more complete mismatch that needs relinking or project creation If you just want machine-readable output, use: ```bash tessl project repair --json ``` When the output names a project, it includes `webUrl`, a link to that project in the Tessl web app. ### When to use each repair action ### Relink to a different project Use this when your current repository is linked to the **wrong Tessl project**. ```bash tessl project repair --relink --workspace --project --yes ``` Use `--relink` when: - Tessl matched the wrong project - your repository should belong to a different existing project - you are in a monorepo and the current package or subpath was associated with the wrong project - the locator in `tessl.json` is missing, stale, or points at the wrong project #### Example: locator drift Your current repository source matches an existing Tessl project, but the project named in `tessl.json` does not. For example: - local `tessl.json` does **not** point to the right project - Tessl can see that the current repo actually matches `team-two/real-project` In that case, relink the current repository to the correct project: ```bash tessl project repair --relink --workspace team-two --project real-project --yes ``` ### Update the source for the current project Use this when the **project is correct**, but Tessl has the wrong **repository source** recorded for it. ```bash tessl project repair --update-source --yes ``` Use `--update-source` when: - the repo remote changed - the repo was renamed or transferred - the repo subpath changed in a way Tessl should now treat as the project’s canonical source - Tessl found the right project by name, but the current repository source no longer matches the stored source #### Example: repoistory name change Your `tessl.json` still points to the correct project, but the underlying repository source has changed. For example: - locator: `team-one/old-name` - recorded source: `https://github.com/acme/old-name` - current local source: `https://github.com/acme/new-name` In that case, keep the same project and update its recorded source: ```bash tessl project repair --update-source --yes ``` Use this when the project identity is still right and only the source has drifted. ### Update the project name Use this when the **repository is still linked correctly**, but the **project name has changed** locally. ```bash tessl project repair --update-name --yes ``` Use `--update-name` when: - you renamed the project in `tessl.json` - the repo still matches the existing project source - you want the Tessl project name to match the new local name #### Example: rename drift Your repository still matches the same project source, but the name in `tessl.json` changed. For example: - old name: `team-one/old-project` - new local name: `team-one/renamed-project` In that case, repair the name without relinking or recreating the project: ```bash tessl project repair --update-name --yes ``` ### How to decide which one to use Use: - `--relink` when the repository should point to a **different existing project** - `--update-source` when the **project is right** but its **recorded source is outdated** - `--update-name` when the **project is right** but its **name changed** A simple rule: - wrong project → **relink** - wrong repo source → **update source** - wrong project name → **update name** ### When repair is not the right command You usually do **not** need repair when: - you are creating a Tessl project for the first time - there is no existing project association yet - Tessl is asking you to create a project before your first eval In those cases, use the normal create or link flow instead. ## Project visible in the web app but missing after cloning **Symptom.** The project appears in the Tessl web app. A fresh clone has no `tessl.json`, and `tessl install` or `tessl init` behaves as if no project exists. **Cause.** A teammate created the project but did not commit `tessl.json` to the repository. Without it the CLI has no stored project link and cannot connect automatically. Running `tessl install` blocks when the backend confirms a match, and `tessl init` offers to link inline when the session is interactive and exactly one project matches. ### The `tessl install` block When the CLI confirms the backend already has a project for this repository, `tessl install ` exits with an error rather than creating a second, disconnected project: ```text A Tessl project already exists for this repository but no tessl.json was found. To link this directory to the existing project, run: tessl init tessl project repair --relink --workspace engteam --project my-project --yes Ask the teammate who created the project to commit tessl.json, so the next clone links to it. ``` When more than one project matches, the relink command uses placeholders and a `Matching projects:` list follows, one `workspace/project` per line, so you can choose the right one and fill in the values. If the backend check cannot run (authentication failure, network error, or timeout), `tessl install` falls through to normal initialization instead of blocking. ### The `tessl init` prompt #### Interactive session with one matching project When the CLI confirms a single matching project and the session is interactive, `tessl init` asks: ```text Link this directory to engteam/my-project? (Y/n) ``` - **Yes**: writes `tessl.json` already linked to the existing project. No relink step is needed. - **No**: writes an unlinked `tessl.json` and prints the relink command after `Init complete!`. #### Non-interactive session, declined prompt, or multiple matching projects When init cannot link inline, it writes an unlinked `tessl.json` and prints the relink command after `Init complete!`. **Single matching project**: the printed command includes the project's workspace and name: ```bash tessl project repair --relink --workspace engteam --project my-project --yes ``` **Multiple matching projects**: the printed command uses placeholders, followed by a list of candidates: ```text tessl project repair --relink --workspace --project --yes Matching projects: engteam/project-a engteam/project-b ``` Choose the correct project from the list and substitute its workspace and name into the command. ### Running from a subdirectory When the CLI confirms the project is registered at the repository root but the command runs from a subdirectory: - `tessl install` exits with an error that names the repository root and the recovery commands to run from there. - `tessl init` stops without writing anything and tells you to run `tessl init` from the repository root. Move to the repository root and run the recovery from there. If the backend check cannot run, both commands fall through to normal initialization instead. ### The commit nudge When `tessl init` creates a new `tessl.json` that is not yet tracked by git, the CLI prints: ```text Commit tessl.json so teammates connect to the same project. Leaving it uncommitted is the most common cause of project mismatch errors. ``` This nudge fires when the manifest is linked, either for a fresh project or after the user accepts the link prompt. When init writes an unlinked manifest (user declined or non-interactive path), the nudge is suppressed; run the relink command first, then commit. ### Prevention Commit `tessl.json` immediately after running `tessl init` or `tessl project create`. Every teammate who clones the repository will then connect to the same project without needing to relink.