> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Manage projects from the CLI

Start with `tessl init` or `tessl project create`. Both commands recognize a Tessl project that already matches the current repository and link it automatically when there is one clear match.

If you're blocked when starting an eval, this is usually the page you need.

Creating a Tessl project does not create a new Git repository. It creates the Tessl project for the repository you are already working in.

### When you are asked to create a project

Tessl asks for a project when it needs to identify the repository behind the current directory.

This happens most often when you run an eval from a repository that is not linked yet.

### Automatic setup

Run `tessl init` to set up Tessl and your coding agents. If the repository already has a project that Tessl discovered from GitHub, `tessl init` records that link in a new `tessl.json`. It does not create a duplicate project.

Run `tessl project create` when you only need to set up the project link. The command creates `tessl.json` if it is missing, then:

- Links the project automatically when exactly one project matches the repository and package path
- Creates a project when none match
- Shows the matching projects and the resolving command when more than one match is available

Both commands show the repository, matched project, manifest link, and next action after an automatic match.

### Which explicit command should I use?

| Command                | Use it when                                      | What it does                                                                    |
| ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- |
| `tessl project create` | This directory is not linked yet                 | Links one matching project automatically, or creates a project when none match  |
| `tessl project link`   | Several projects match and you need to choose    | Links this directory to the selected existing project                           |
| `tessl project repair` | An existing local link is missing, wrong, or old | Inspects the link and applies an explicit relink, source update, or name update |
| `tessl project delete` | You no longer need a project                     | Deletes the project and keeps its run history                                   |

### `tessl project create`

Sets up the Tessl project link for the current repository checkout.

Use this when the current repository is not linked yet. The command checks the projects across your organization before it creates anything.

If no `tessl.json` is found in this directory or any parent directory, the command creates one before proceeding. You do not need to run `tessl init` first.

If a `tessl.json` already exists in a parent directory (but not in the current directory), the command stops and asks you to pass `--nested`. Run it again with `--nested` to create a new `tessl.json` in the current directory and a separate project for it, rather than reusing the parent project.

When one existing project matches, the command records its full `workspace/project` link in `tessl.json`. When no project matches, it creates one and records the new link. Use `--new` with an explicit workspace and project name only when you intentionally need another project for the same repository.

### `tessl project link`

Links the current repository to an existing Tessl project.

Use this when several projects match and you need to choose one explicitly.

This command only links to an existing project. It does not create a new one.

If you want to create a brand new project for this repository, use `tessl project create` instead.

### `tessl project repair`

Inspects or repairs the Tessl project link for the current repository.

Use this when the repository should already be linked to a project, but the link is missing, broken, outdated, or no longer matches the expected repository.

Use `--relink` to connect the repository to a different existing project, `--update-source` to keep the linked project but approve this repository as its source, and `--update-name` to rename the linked project to match `tessl.json`.

### `tessl project delete`

Deletes a Tessl project without opening the web app.

Name the project by its `workspace/project` reference, its ID, or its name. A name alone must match exactly one project in your organization. When it matches projects in several workspaces, the command lists them and asks you to use the `workspace/project` reference or the ID.

You need the publisher role or higher in the project's workspace. The project leaves normal views and its name and repository link become free for reuse. Its run history is kept.

The command asks for confirmation in an interactive shell. Pass `--yes` to skip it.

### What happens after linking

Once a repository is linked:

- Evals attach to that Tessl project
- The CLI and app can show one shared evaluation history