> For the complete documentation index, see [llms.txt](https://docs.tessl.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tessl.io/projects/repairing-projects.md). # Repairing projects Understand how to diagnose and fix issues with 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 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: ``` 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: ``` 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: ``` 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: ``` 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.tessl.io/projects/repairing-projects.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.