Ctrlk
WebsitePress Kit

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:

When to use each repair action

Relink to a different project

Use this when your current repository is linked to the wrong Tessl project.

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:

Update the source for the current project

Use this when the project is correct, but Tessl has the wrong repository source recorded for it.

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:

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.

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:

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.

PreviousManage projects from the CLINextProjects in the app

Last updated