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:

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:

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.

tessl project repair --relink --workspace <workspace> --project <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:

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.

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:

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.

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:

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 <plugin> 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:

$ 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 <name-or-id> --project <name> --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.