> 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/reference/cli-commands.md).

# CLI commands

The Tessl CLI provides commands for managing plugins, workspaces, authentication, repository configuration, and Tessl projects. This page provides a comprehensive reference for all available commands.

{% hint style="info" %}
On this page, **repository** means your Git repository. **Tessl project** means the stable home for Tessl in that repository.
{% endhint %}

## Getting started

### tessl help command

To see all available commands, run:

```sh
tessl --help
```

To get detailed information about a specific command or command group, use the `--help` flag:

```sh
tessl <command> --help
tessl <command-group> <subcommand> --help
```

***

## Authentication

### tessl login

Authenticate with Tessl.

**Usage**

```sh
tessl login
```

**Alternative**

```sh
tessl auth login
```

### tessl logout

Sign out and clear credentials.

**Usage**

```sh
tessl logout
```

**Alternative**

```sh
tessl auth logout
```

### tessl whoami

Show current authenticated user.

**Usage**

```sh
tessl whoami
```

**Alternative**

```sh
tessl auth whoami
```

***

## Setup and initialization

### tessl init

Set up your repository and configure your coding agent.

**Usage**

```sh
tessl init [--agent <name>]... [--name <name>]
```

**Flags**

* `--agent` (string, optional, repeatable): Configure MCP for coding agent. Supported values: `claude-code`, `cursor`, `gemini`, `antigravity`, `codex`, `openhands`, `openclaw`, `copilot`, `copilot-vscode`, `agents`, `tessl-agent`. Can specify multiple agents. See [Custom Agents](/reference/custom-agent-setup.md) for information on configuring additional agents.
* `--name` (string, optional): Project name for new `tessl.json` (default: current directory name)

**Notes**

* Configures MCP server settings for AI coding agents
* Creates a `tessl.json` manifest at the repository root

**Examples**

```sh
# Basic initialization with default settings
tessl init

# Initialize and configure Cursor integration
tessl init --agent cursor

# Initialize with multiple agents
tessl init --agent cursor --agent claude-code
```

### tessl project

Create, link, or repair the Tessl project for this repository.

A Tessl project gives Tessl a stable place to attach eval runs and other repository-connected data, so your results stay tied to your codebase over time.

Use these commands to create a new project, link this checkout to an existing project, or repair a missing or broken reference in `tessl.json`. For a workflow guide, see [Manage projects from the CLI](/projects/manage-projects-from-the-cli.md).

**Usage**

```sh
tessl project <create|link|repair>
```

### tessl project create

Create a new Tessl project for the current repository.

**Usage**

```sh
tessl project create [--nested] [--new] [--workspace <name-or-id>] [<project-name>]
```

**Flags**

* `--nested` (boolean, optional): Required when a parent directory has a `tessl.json` but the current directory has none. Creates a separate `tessl.json` and project for the current directory instead of reusing the parent project.
* `--new` (boolean, optional): Create a new project for a different workspace. Use with `--workspace` and provide a project name when you intentionally want a separate new project for the same repository.
* `--workspace` (string, optional): Name or ID of workspace

**Arguments**

* `project-name` (string, optional): Name for the new project. If omitted, you'll be prompted.

**Notes**

* Use this when this repository is not linked to a project yet and you want to create one in Tessl
* This command always creates a new project
* If this repository should use a project that already exists, use `tessl project link` instead

### tessl project link

Link the current repository to an existing Tessl project.

**Usage**

```sh
tessl project link [--workspace <name-or-id>]
```

**Flags**

* `--workspace` (string, optional): Name or ID of workspace to search

**Notes**

* Use this when the project already exists in Tessl and you want this repository to use it
* This command only links to an existing project
* If you want to create a brand new project for this repository, use `tessl project create` instead

### tessl project repair

Inspect or repair the Tessl project link for the current repository.

**Usage**

```sh
tessl project repair [--json] [--relink] [--workspace <name-or-id>] [--project <name>] [--update-source] [--update-name] [--yes]
```

**Flags**

* `--json` (boolean, optional): Output as JSON, for automation or agent workflows
* `--relink` (boolean, optional): Relink this repository to a different existing project
* `--workspace` (string, optional): Workspace name or ID for `--relink`
* `--project` (string, optional): Project name for `--relink` target
* `--update-source` (boolean, optional): Approve this repository as the linked project source
* `--update-name` (boolean, optional): Rename the linked project to match `tessl.json`
* `--yes` / `-y` (boolean, optional): Confirm and apply requested repair

**Notes**

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

### tessl project list

List all projects in a workspace.

**Usage**

```sh
tessl project list [--workspace <name>] [--json]
```

**Flags**

* `--workspace` (string, optional): Name or ID of workspace.
* `--json` (boolean, optional): Output as JSON.

**Notes**

* Shows every project you can access in the selected workspace, with its name, ID, and source.
* The workspace is resolved in this order: `--workspace`, the `TESSL_WORKSPACE` environment variable, the project linked in `tessl.json`, then the workspace prefix in a `.tessl-plugin/plugin.json` when no `tessl.json` exists. If none of those apply and you belong to more than one workspace, you are prompted to pick one, or must pass `--workspace` in a non-interactive shell.

**Examples**

```sh
# List projects in the resolved workspace
tessl project list

# List projects in a specific workspace
tessl project list --workspace engteam

# Output as JSON
tessl project list --json
```

***

## Project dependencies

### tessl install

Install plugins into your repository. plugins are versioned bundles of reusable, agent-agnostic context that make coding agents more effective. They can contain skills, documentation, and rules.

**Alias**: `tessl i`

**Usage**

```sh
tessl install [--global] [--skill <value>]... [--yes] [--verbose] [--watch-local] [--accept-warnings] [--strict] [--agent <name>]... <source>...
```

**Arguments**

* `source` (string, required): plugin or GitHub URL to install. Can be:
  * Registry plugin: `workspace/plugin[@version]` (version optional, defaults to latest)
  * GitHub repository:
    * Full URL: `https://github.com/owner/repo`
    * Shorthand: `github:owner/repo` (e.g., `github:softaworks/agent-toolkit`)
  * File path: `file:<path>` to install from local directory

**Flags**

* `--global` / `-g` (boolean, optional): Install plugins globally to `~/.tessl/` instead of the current repository. Global plugins are available across all your repositories.
* `--skill` (string, repeatable, optional): Select specific skills to install from GitHub repositories. Used when a repository contains multiple skills. If omitted, you'll be prompted interactively to select from available skills. Can be specified multiple times to install multiple skills from the same repository.
* `--yes` (boolean, optional): Skip confirmation prompts and auto-select all skills
* `--verbose` / `-v` (boolean, optional): Show detailed warning messages during installation
* `--watch-local` (boolean, optional): Watch local file-source plugins and reinstall on changes
* `--accept-warnings` (boolean, optional): Pre-accept install policy warnings (no interactive prompt)
* `--strict` (boolean, optional): Fail if a version is too new rather than installing an older fallback
* `--agent` (string, optional, repeatable): Override agents to install for. Supported values: `claude-code`, `cursor`, `gemini`, `antigravity`, `codex`, `openhands`, `openclaw`, `copilot`, `copilot-vscode`, `agents`, `tessl-agent`.

**Notes**

* Plugins are installed to `.tessl/plugins/<plugin-name>/` in your repository (or `~/.tessl/plugins/` when using `--global`)
* Your repository's `tessl.json` is automatically updated with the plugin reference
* If a plugin is already installed and up-to-date, it will be skipped
* **GitHub URL formats**: `https://github.com/owner/repo`, `github:owner/repo`, or with branch/path: `https://github.com/owner/repo/tree/main/skills/pdf`
* **File system installation**: Use `file:<path>` to install from a local directory (`.tessl-plugin/plugin.json` expected in the path)
* **Install policy warnings**: If a plugin triggers install policy warnings (such as critical or high Snyk security findings), you will be asked for permission before installation continues. You can always choose to proceed — installation is never blocked. Use `--accept-warnings` to pre-accept these warnings and skip the prompt.

**Examples**

```sh
# Install a specific plugin from registry
tessl install tessl/svelte@5.38.0

# Install multiple plugins from registry
tessl install tessl/svelte tessl/react

# Install from file system (.tessl-plugin/plugin.json is expected in the specified path)
tessl install file:<path to plugin>

# Install from GitHub repository with interactive skill selection
tessl install https://github.com/anthropics/skills

# Install using GitHub shorthand syntax
tessl install github:softaworks/agent-toolkit

# Install specific skill by name from GitHub repository (when repo has multiple skills)
tessl install https://github.com/anthropics/skills --skill pdf

# Install multiple skills by name from GitHub repository using shorthand
tessl install github:anthropics/skills --skill pdf --skill pptx

# Install from specific branch and path in GitHub repository
tessl install https://github.com/anthropics/skills/tree/main/skills/pdf

# Install from a specific commit (useful when the registry shows security results for that commit)
tessl install engteam/my-skill@abc1234

# Install a plugin globally (available across all repositories)
tessl install --global tessl/svelte
```

### tessl search

Search for plugins and skills in the Tessl registry by name, PURL, or HTTP URL.

**Usage**

```sh
$ tessl search [--global] [--type skills|docs|rules] [--org <slug-or-id> | --workspace <org/workspace-or-id>] [--json] [<query>]
```

**Flags**

* `--global` / `-g` (boolean, optional): Install selected plugins and skills globally to `~/.tessl/` instead of the current project
* `--type` (string, optional): Filter by content type. Supported values: `skills`, `docs`, `rules`
* `--org` (string, optional): Limit results to an organization you can access, identified by its slug or ID
* `--workspace` (string, optional): Limit results to a workspace you can access, identified by `org/workspace` or its ID
* `--json` (boolean, optional): Output search results as JSON

`--org` and `--workspace` require authentication and cannot be used together.

**Arguments**

* `query` (string, optional): Search query (name, PURL, or HTTP URL). If omitted, you'll be prompted interactively.

**Examples**

```sh
# Search for plugins matching "svelte"
$ tessl search svelte
# Search and install selected results globally
$ tessl search --global svelte

# Search for skills in an organization
$ tessl search --type skills --org acme code-review

# Search for skills in a workspace
$ tessl search --type skills --workspace acme/engteam code-review

# Interactive search
$ tessl search
```

### tessl uninstall

Uninstall plugins from your repository.

**Usage**

```sh
tessl uninstall [--global] [--skill <value>]... <workspace/plugin>
```

**Arguments**

* `workspace/plugin` (string, required): Full plugin name in the format `workspace/plugin`

**Flags**

* `--global` / `-g` (boolean, optional): Uninstall plugins from the global `~/.tessl/` directory instead of the current repository
* `--skill` (string, repeatable, optional): Remove specific skills instead of the entire plugin (repeatable)

**Notes**

* Removes the plugin from `tessl.json` and deletes files from `.tessl/plugins/`
* Does not require authentication (local operation only)

**Examples**

```sh
# Uninstall a plugin from the current repository
tessl uninstall tessl/svelte

# Uninstall a globally installed plugin
tessl uninstall --global tessl/svelte
```

### tessl list

List all installed plugins in your repository.

**Usage**

```sh
tessl list [--global] [--json]
```

**Flags**

* `--global` / `-g` (boolean, optional): List plugins installed in global `~/.tessl/` instead of the current repository
* `--json` (boolean, optional): Output plugins as JSON instead of human-readable format

**Notes**

* Lists all plugins installed in your repository based on `tessl.json`
* Shows plugin names in the format `workspace/plugin` with their versions
* Does not require authentication (local operation only)

**Examples**

```sh
# List all installed plugins
tessl list

# List plugins in JSON format
tessl list --json
```

### tessl outdated

Check for available plugin updates.

**Usage**

```sh
tessl outdated [--json]
```

**Flags**

* `--json` (boolean, optional): Output as JSON

**Examples**

```sh
# Check for outdated plugins
tessl outdated

# Output as JSON
tessl outdated --json
```

### tessl update

Update plugins to newer versions.

**Usage**

```sh
tessl update [--yes] [--force] [--global] [--accept-warnings] [--agent <name>]... [<plugin>]
```

**Flags**

* `--yes` / `-y` (boolean, optional): Skip prompts and update all compatible plugins
* `--force` / `-f` (boolean, optional): Include breaking updates
* `--global` / `-g` (boolean, optional): Update plugins installed globally in `~/.tessl/` instead of the current repository
* `--accept-warnings` (boolean, optional): Pre-accept install policy warnings (no interactive prompt)
* `--agent` (string, optional, repeatable): Override agents to sync for. Supported values: `claude-code`, `cursor`, `gemini`, `antigravity`, `codex`, `openhands`, `openclaw`, `copilot`, `copilot-vscode`, `agents`, `tessl-agent`.

**Arguments**

* `plugin` (string, optional): plugin to update in the format `workspace/plugin`. If omitted, updates all plugins.

**Notes**

* If a plugin triggers install policy warnings in the new version (such as critical or high Snyk security findings), you will be asked for permission before the update is applied. Use `--accept-warnings` to pre-accept these warnings and skip the prompt.

**Examples**

```sh
# Update all plugins interactively
tessl update

# Update all plugins without prompts
tessl update --yes

# Update a specific plugin
tessl update engteam/my-plugin

# Include breaking updates
tessl update --force
```

***

## Skill management

### tessl skill new

Create a new skill with an interactive wizard or using flags.

**Usage**

```sh
tessl skill new [--name NAME] [--description DESCRIPTION] [--workspace WORKSPACE] [--path PATH] [--install] [--public]
```

**Flags**

* `--name` (string, optional): Skill name
* `--description` (string, optional): When the skill should be triggered
* `--workspace` (string, optional): Workspace for the skill (default: local)
* `--path` (string, optional): Directory path where the skill will be created
* `--install` (boolean, optional): Automatically install in the current repository after creation
* `--public` (boolean, optional): Make the skill public (default: private)

**Notes**

* If flags are omitted, an interactive wizard will guide you through skill creation
* The skill will be created as a directory with the proper Agent Skills specification structure
* Use `--install` to immediately add the skill to your local agent configuration

**Examples**

```sh
# Create a skill interactively
tessl skill new

# Create a skill with all details specified
tessl skill new --name "commit-conventions" --description "Enforce commit message standards" --workspace myteam --install
```

### tessl skill import

Create `.tessl-plugin/plugin.json` from a local `SKILL.md` file.

**Usage**

```sh
tessl skill import [--workspace WORKSPACE] [--public] [--force] [<path>]
```

**Flags**

* `--workspace` (string, optional): Workspace for the skill (default: local)
* `--public` (boolean, optional): Make skill public (default: private)
* `--force` (boolean, optional): Overwrite existing `.tessl-plugin/plugin.json` without prompting

**Arguments**

* `path` (string, optional): Local path to directory containing SKILL.md or to SKILL.md file. Defaults to current directory if omitted.

**Examples**

```sh
# Import from current directory
tessl skill import

# Import from a specific path
tessl skill import ./my-skill

# Import and make public
tessl skill import --public --workspace myteam ./my-skill
```

### tessl skill lint

Validate skill structure and contents.

**Usage**

```sh
tessl skill lint [<source>]
```

**Arguments**

* `source` (string, optional): Path to skill folder or plugin.json. Defaults to current directory if omitted.

**Notes**

* Checks for required files and proper structure
* Validates frontmatter fields (name, description, etc.)
* Verifies conformance to the Agent Skills specification at [agentskills.io/specification](https://agentskills.io/specification)
* Returns validation errors and warnings

**Examples**

```sh
# Lint skill in current directory
tessl skill lint

# Lint skill at specific directory path
tessl skill lint ./my-skill

```

### tessl skill publish

Import (if needed) and publish skill to the registry. This command bundles skills, rules, documentation into a plugin.

**Usage**

```sh
tessl skill publish [--workspace WORKSPACE] [--public] [--force] [--bump patch|minor|major] [--dry-run] [--skip-evals] [--with-scenario-quality-check] [--eval-scenarios <path>] [--resolve-symlinks] [<path>]
```

**Flags**

* `--workspace` (string, optional): Workspace for the skill (used if importing)
* `--public` (boolean, optional): Make skill public (used if importing)
* `--force` (boolean, optional): Overwrite existing `.tessl-plugin/plugin.json` without prompting
* `--bump` (string, optional): Auto-bump version if it already exists in the registry. Supported values: `patch`, `minor`, `major`
* `--dry-run` (boolean, optional): Run all pre-publish checks without publishing
* `--skip-evals` (boolean, optional): Skip publishing eval scenarios from evals/ directory
* `--with-scenario-quality-check` (boolean, optional): Exclude misleading scenarios from the publish-time eval run
* `--eval-scenarios` (string, optional): Path to eval scenarios directory (default: `<path>/evals`)
* `--resolve-symlinks` (boolean, optional): Resolve symlinked files to their target contents when packing

**Arguments**

* `path` (string, optional): Path to the skill directory to publish. Defaults to current directory if omitted.

**Notes**

* Skills are automatically linted before publishing
* Published skills are versioned based on the version in the skill manifest
* Eval scenarios from the `evals/` directory are published by default; use `--skip-evals` to exclude them
* **Automatic evaluation**: When published, skills are automatically evaluated and review scores are calculated (see [Check a skill's quality using review](/improving-your-skills/reviewing-skills.md))

**Examples**

```sh
# Publish skill from current directory
tessl skill publish

# Publish to a specific workspace
tessl skill publish --workspace myteam ./my-skill

# Publish publicly
tessl skill publish --public
```

### tessl skill unpublish

Prints guidance explaining that skills cannot be unpublished on their own. Performs no registry action. `tessl skill archive` and `tessl skill delete` print the same guidance.

Skills are published inside a plugin. To remove a published skill, delete the skill and republish the plugin, unpublish the plugin, or archive the plugin. See [tessl plugin unpublish](#tessl-plugin-unpublish) and [tessl plugin archive](#tessl-plugin-archive).

***

## Tessl Review

The `tessl review` family runs an asynchronous review pipeline server-side. These commands require authentication; `run` and `fix` also require a workspace. The pipeline is bundle-aware, and `tessl review run` polls until it completes. This is the primary path for authenticated users and CI gating.

### tessl review run

Run an asynchronous **quality** review of a skill — it scores the skill against a reviewer rubric. `tessl review run` is shorthand for `tessl review run quality`; to run a security scan instead, use `tessl review run security` (documented below). Requires authentication and a workspace.

**Usage**

```sh
tessl review run [--json] [--workspace WORKSPACE] [--threshold <percent>] [--label <text>] [--force] [--review-plugin <ref>] [--no-wait] [<path>]
```

**Flags**

* `--json` (boolean, optional): Output as JSON
* `--workspace` / `-w` (string, optional): Workspace name or ID. Required when `--json` is set
* `--threshold` (number, optional): Exit non-zero if the review score is below this percentage. `0` never fails (skips validation and score gating)
* `--label` / `-l` (string, optional): Label to describe this review run
* `--force` / `-f` (boolean, optional): Run a fresh review even when cached results exist
* `--review-plugin` (string, optional): Reviewer plugin — a path to a local plugin directory, or a registry ref `workspace/plugin[@version]`. Requires a paid plan; on a Free organisation, passing this flag returns an upgrade error
* `--wait` / `--no-wait` (boolean, optional): Wait for the review to finish before returning (default: wait; use `--no-wait` to submit and return the run id immediately, then reconnect with `tessl review view`). Cannot be combined with `--threshold`, which needs the completed score

**Arguments**

* `path` (string, optional): Path to a skill file or skill directory. Defaults to current directory if omitted.

**Notes**

* Requires authentication; sign in with `tessl login` or set the `TESSL_TOKEN` API key in the environment
* `--workspace` is required when `--json` is set, since non-interactive runs cannot prompt for a workspace
* The command polls until the review completes, then prints the results
* `--threshold` causes a non-zero exit when the score falls below the percentage, making it a CI gate
* Press Ctrl+C to detach — the review continues server-side and can be viewed later with `tessl review view`
* `run` has two subcommands: `quality` (the default, documented here) and `security` (below). `tessl review run quality` is the explicit form of the default

**Examples**

```sh
# Review the skill in the current directory
tessl review run --workspace engteam

# Review a skill at a specific path
tessl review run ./my-skill --workspace engteam

# CI gate: fail if the score is below 80%
tessl review run ./my-skill --workspace engteam --json --threshold 80

# Review with a specific reviewer plugin
tessl review run ./my-skill --workspace engteam --review-plugin engteam/my-reviewer
```

### tessl review run security

Run an asynchronous security scan of a skill, powered by Snyk. Reports findings and the highest severity. Requires authentication and a workspace.

**Usage**

```sh
tessl review run security [--json] [--workspace WORKSPACE] [--label <text>] [--force] [--fail-on <severity>] [--no-wait] [<path>]
```

**Flags**

* `--json` (boolean, optional): Output as JSON
* `--workspace` / `-w` (string, optional): Workspace name or ID. Required when `--json` is set
* `--label` / `-l` (string, optional): Label to describe this security review run
* `--force` / `-f` (boolean, optional): Run a fresh scan even when cached results exist
* `--fail-on` (string, optional): Exit non-zero if the highest severity is at or above this level: `low`, `medium`, `high`, `critical`
* `--wait` / `--no-wait` (boolean, optional): Wait for the scan to finish before returning (default: wait; use `--no-wait` to submit and return the run id immediately, then reconnect with `tessl review view`). Cannot be combined with `--fail-on`, which needs the completed findings

**Arguments**

* `path` (string, optional): Path to a skill file or skill directory. Defaults to current directory if omitted.

**Notes**

* Requires authentication; sign in with `tessl login` or set the `TESSL_TOKEN` API key in the environment
* The scan runs server-side; the command polls until it completes, then prints the findings and the highest severity
* `--fail-on` gates the exit code on severity, making it a CI gate — the security equivalent of `--threshold` on a quality review

**Examples**

```sh
# Security-scan the skill in the current directory
tessl review run security --workspace engteam

# Scan a skill at a specific path
tessl review run security ./my-skill --workspace engteam

# CI gate: fail if any finding is high or critical
tessl review run security ./my-skill --workspace engteam --json --fail-on high
```

### tessl review view

View results for a review run of either kind. The run ID resolves whether it is a quality or a security review, and the results are rendered accordingly.

**Usage**

```sh
tessl review view [--json] [--last] [--threshold <percent>] [--fail-on <severity>] [--workspace <name>] [<id>]
```

**Flags**

* `--json` (boolean, optional): Output as JSON, in the same shape as `tessl review run --json`
* `--last` (boolean, optional): View results for the most recent review run
* `--threshold` (number, optional): Quality reviews only. Exit non-zero if the review score is below this percentage (0-100)
* `--fail-on` (string, optional): Security reviews only. Exit non-zero if the highest severity is at or above this level: `low`, `medium`, `high`, `critical`
* `--workspace` / `-w` (string, optional): Workspace name or ID. Only applies with `--last`; an explicit review run ID already identifies its workspace.

**Arguments**

* `id` (string, optional): Review run ID. Provide an ID or use `--last`.

**Notes**

* Provide a review run ID or use `--last`; one is required
* The gate flag follows the run's kind: `--threshold` gates a quality run, `--fail-on` gates a security run. Passing the flag for the other kind is a usage error
* `--workspace` is only accepted with `--last`; passing it alongside an explicit review run ID fails with a validation error

**Examples**

```sh
# View a specific review run
tessl review view abc123

# View the most recent review run
tessl review view --last

# Re-check a stored run against a threshold
tessl review view abc123 --json --threshold 80
```

### tessl review list

List recent review runs.

**Usage**

```sh
tessl review list [--json] [--limit <count>] [--workspace WORKSPACE]
```

**Flags**

* `--json` (boolean, optional): Output as JSON
* `--limit` (number, optional): Maximum number of review runs to display (default: 20)
* `--workspace` / `-w` (string, optional): Workspace name or ID

**Examples**

```sh
# List recent review runs
tessl review list

# List the 50 most recent runs
tessl review list --limit 50

# List runs for a specific workspace
tessl review list --workspace engteam
```

### tessl review retry

Re-run a failed review run.

**Usage**

```sh
tessl review retry [--json] [--workspace <name>] [--last] [<id>]
```

**Flags**

* `--json` (boolean, optional): Output as JSON
* `--workspace` / `-w` (string, optional): Workspace name or ID. Only applies with `--last`; an explicit review run ID already identifies its workspace.
* `--last` (boolean, optional): Retry the most recent review run

**Arguments**

* `id` (string, optional): Review run ID to retry. Provide an ID or use `--last`.

**Notes**

* `--workspace` is only accepted with `--last`; passing it alongside an explicit review run ID fails with a validation error

**Examples**

```sh
# Retry a specific review run
tessl review retry abc123

# Retry the most recent review run
tessl review retry --last

# Retry the most recent review run in a specific workspace
tessl review retry --last --workspace engteam
```

### tessl review fix

Improve a skill by running an automated review-and-fix loop server-side. Requires authentication and a workspace.

**Usage**

```sh
tessl review fix [--json] [--workspace WORKSPACE] [--threshold <percent>] [--max-iterations <count>] [--yes] [--review-plugin <ref>] [<path>]
```

**Flags**

* `--json` (boolean, optional): Output as JSON
* `--workspace` / `-w` (string, optional): Workspace name or ID
* `--threshold` (number, optional): Stop once a review scores at or above this percentage (0-100, default 90)
* `--max-iterations` (number, optional): Maximum improve→review iterations to attempt (1-10, default 3)
* `--yes` / `-y` (boolean, optional): Apply the improved skill without confirmation
* `--review-plugin` (string, optional): Reviewer plugin — a path to a local plugin directory, or a registry ref `workspace/plugin[@version]`. Requires a paid plan; on a Free organisation, passing this flag returns an upgrade error

**Arguments**

* `path` (string, optional): Path to a local skill file or skill directory. Defaults to current directory if omitted.

**Notes**

* Requires authentication; sign in with `tessl login` or set the `TESSL_TOKEN` API key in the environment
* `--workspace` is required when `--json` is set, since non-interactive runs cannot prompt for a workspace
* Runs an asynchronous improve→review loop, stopping early once `--threshold` is met

**Examples**

```sh
# Improve the skill in the current directory
tessl review fix --workspace engteam

# Improve until the score reaches 90%, up to 5 iterations
tessl review fix ./my-skill --workspace engteam --threshold 90 --max-iterations 5

# Apply improvements without a confirmation prompt
tessl review fix ./my-skill --workspace engteam --yes
```

***

## Plugin management

### tessl plugin new

Create a new plugin with an interactive wizard.

**Usage**

```sh
tessl plugin new [--name <workspace/plugin-name>] [--summary <description>] [--path <path>] [--rules <rule-name>] [--rule-description <description>] [--workspace <workspace>] [--skill] [--skill-name <name>] [--skill-description <description>] [--install] [--public]
```

**Flags**

* `--name` (string, optional): plugin name in format `workspace/plugin-name`
* `--summary` (string, optional): Brief description of the plugin
* `--path` (string, optional): Directory path where plugin will be created
* `--rules` (string, optional): Include rule by name
* `--rule-description` (string, optional): Initial rule instructions to include in generated rule file
* `--workspace` (string, optional): Workspace for the plugin
* `--skill` (boolean, optional): Include a skill in the plugin
* `--skill-name` (string, optional): Skill name (implies `--skill`)
* `--skill-description` (string, optional): Skill description (required with `--skill` or `--skill-name`)
* `--install` (boolean, optional): Automatically install in the current repository
* `--public` (boolean, optional): Make plugin public (default: private)

**Notes**

* Creates a new plugin directory with a basic `.tessl-plugin/plugin.json` template
* If run without flags, launches an interactive wizard to guide you through plugin creation
* For non-interactive use, include at least one component with `--skill`, `--skill-name`, or `--rules`
* Use `--skill` or `--skill-name` to create a plugin with a skill component

**Examples**

```sh
# Interactive wizard mode
tessl plugin new

# Create a plugin with specific options
tessl plugin new --name myworkspace/my-skill --summary "My skill description" --path ./my-skill-plugin

# Create a plugin with a skill
tessl plugin new --name myworkspace/my-skill --skill --skill-name "my-skill" --skill-description "Description of my skill"

# Create and automatically install
tessl plugin new --name myworkspace/my-skill --install
```

### tessl plugin lint

Validate plugin structure and contents

**Usage**

```sh
tessl plugin lint [<source>]
```

**Arguments**

* `source` (string, optional): Path to the plugin directory to lint. Defaults to current directory if omitted.

### tessl plugin migrate

Migrate `tile.json` to `.tessl-plugin/plugin.json`.

**Usage**

```sh
tessl plugin migrate [--force] [<path>]
```

**Flags**

* `--force` (boolean, optional): Overwrite existing `.tessl-plugin/plugin.json`

**Arguments**

* `path` (string, optional): Path to plugin directory. Defaults to current directory if omitted.

### tessl plugin pack

Package a plugin into a .tgz file.

**Usage**

```sh
tessl plugin pack [--output path] [<source>]
```

**Flags**

* `--output` (string, optional): Output path for .tgz file. If omitted, uses the plugin name and version to create a file in your current directory.

**Arguments**

* `source` (string, optional): Path to plugin folder. Defaults to current directory if omitted.

### tessl plugin info

Show plugin details from the registry.

**Usage**

```sh
tessl plugin info [<name-or-path>]
```

**Arguments**

* `name-or-path` (string, optional): plugin name (`workspace/plugin[@version]`) or path to plugin directory. Defaults to current directory if omitted.

**Examples**

```sh
# Show info for plugin in current directory
tessl plugin info

# Show info for a specific plugin
tessl plugin info engteam/my-plugin

# Show info for a specific version
tessl plugin info engteam/my-plugin@1.0.0
```

### tessl plugin publish

Publish plugins to the Tessl registry. This command bundles skills, rules, documentation into a plugin.

**Usage**

```sh
tessl plugin publish [--dry-run] [--bump patch|minor|major] [--skip-evals] [--with-scenario-quality-check] [--workspace <workspace>] [--version <version>] [--verbose] [<path>]
```

**Flags**

* `--dry-run` (boolean, optional): Run all pre-publish checks without publishing
* `--bump` (string, optional): Auto-bump version if it already exists in the registry. Supported values: `patch`, `minor`, `major`
* `--skip-evals` (boolean, optional): Skip publishing eval scenarios from evals/ directory
* `--with-scenario-quality-check` (boolean, optional): Have the backend's LLM judge filter out misleading scenarios (low feasibility, rubric leakage, low value) from the publish-time eval run. Equivalent to `tessl eval run --quality-check` for the eval that runs as part of publishing.
* `--workspace` (string, optional): Workspace to publish under when the plugin manifest name is flat (no `workspace/` prefix)
* `--version` (string, optional): Version to publish when the plugin manifest omits one
* `--verbose` / `-v` (boolean, optional): Print every archived file with the reason it was included

**Arguments**

* `path` (string, optional): Path to the plugin directory to publish. Defaults to current directory if omitted.

**Examples**

```sh
# Publish a plugin from current directory
tessl plugin publish

# Publish a plugin from a specific directory
tessl plugin publish path/to/my/plugin
```

{% hint style="info" %}
Not sure what your published plugin's URL will look like? See [Workspaces](/reference/workspaces.md#how-workspaces-appear-in-the-registry) to learn how workspace and plugin names map to Registry URLs.
{% endhint %}

### tessl plugin unpublish

Unpublish plugins from the registry (within 2 days of publishing).

**Usage**

```sh
tessl plugin unpublish [--plugin <workspace/plugin@version>]
```

**Flags**

* `--plugin` (string, optional): plugin to unpublish in the format `workspace/plugin@version`. If omitted, you'll be prompted.

**Notes**

* Only available within 2 days of publishing

**Examples**

```sh
# Unpublish a specific plugin version
tessl plugin unpublish --plugin myworkspace/myplugin@1.0.0

# Interactive mode
tessl plugin unpublish
```

### tessl plugin archive

Archive plugins in the registry.

**Usage**

```sh
tessl plugin archive [--plugin <workspace/plugin[@version]>] --reason <reason>
```

**Flags**

* `--plugin` (string, optional): plugin to archive in the format `workspace/plugin` (archives all versions) or `workspace/plugin@version` (archives a single version)
* `--reason` (string, required): Reason for archiving the plugin

**Notes**

* Prevents new installations while preserving existing installations

**Examples**

```sh
# Archive a specific plugin version
tessl plugin archive --plugin engteam/myplugin@1.0.0 --reason "Deprecated in favor of v2"

# Archive all versions of a plugin
tessl plugin archive --plugin engteam/myplugin --reason "No longer maintained"
```

***

## Organization management

### tessl org list

List all organizations that you are a member of.

**Usage**

```sh
tessl org list
```

### tessl org usage

Show your Tessl credit usage.

**Usage**

```sh
tessl org usage [--org <nameOrId>] [--json]
```

**Flags**

* `--org` (string, optional): Organization name or ID. You are prompted when you belong to several.
* `--json` (boolean, optional): Output as JSON. The payload contains `plan` and `credits` fields.

**Examples**

```sh
# Show credit usage
tessl org usage

# Show usage for a specific organization
tessl org usage --org my-org

# Output as JSON
tessl org usage --json
```

***

## Workspace management

Workspaces enable you to create private collections of plugins that are restricted to yourself or your organization. You can control member access and permissions. To learn more, see [Distributing via registry](/distribute/distributing-via-registry.md).

### tessl workspace create

Create a new workspace.

**Usage**

```sh
tessl workspace create [--org <nameOrId>] [<name>]
```

**Flags**

* `--org` (string, optional): Organization name or ID to own the workspace. When omitted and you belong to several organizations, interactive terminals prompt you to pick one; noninteractive callers must pass `--org <nameOrId>`.

**Arguments**

* `name` (string, optional): Name for the workspace. The name must be lowercase. If omitted, you'll be prompted.

**Examples**

```sh
# Create a workspace
tessl workspace create myworkspace

# Interactive creation
tessl workspace create

# Create a workspace in a specific organization
tessl workspace create --org 01935e2c-1234-5678-abcd-ef0123456789 engteam
```

### tessl workspace list

List all workspaces that you are a member of.

**Usage**

```sh
tessl workspace list [--has-publish-access]
```

**Flags**

* `--has-publish-access` (boolean, optional): Only show workspaces where you have permission to publish.

**Examples**

```sh
# List all workspaces you belong to
tessl workspace list

# List only workspaces you can publish to
tessl workspace list --has-publish-access
```

### tessl workspace delete

Delete an existing workspace.

**Usage**

```sh
tessl workspace delete [<name>]
```

**Arguments**

* `name` (string, optional): The name or ID of the workspace. If omitted, you'll be prompted.

**Examples**

```sh
# Delete a workspace
tessl workspace delete myworkspace

# Interactive deletion
tessl workspace delete
```

If a workspace has published a public plugin, deleting it permanently reserves its name: the name cannot be used again, in this organization or any other. To move a workspace between organizations, do not delete it. Email <support@tessl.io> and we can move it for you after a review.

### tessl workspace add-member

Add a user to a workspace with specified permissions.

**Usage**

```sh
tessl workspace add-member [--workspace <name>] [--username <username>] [--role <role>]
```

**Flags**

* `--workspace` (string, optional): Name or ID of workspace
* `--username` (string, optional): Username or ID of user to add
* `--role` (string, optional): Role to assign. Supported values: `member`, `publisher`, `manager`, `owner`

See [Roles](/administrators/roles.md) for more information

**Examples**

```sh
# Add a user to the workspace with a member role
tessl workspace add-member --workspace myworkspace --username johnsmith --role member

# Add a user to the workspace with an owner role
tessl workspace add-member --workspace myworkspace --username janesmith --role owner

# Interactive mode (prompts for all fields)
tessl workspace add-member
```

### tessl workspace remove-member

Remove a user from a workspace.

**Usage**

```sh
tessl workspace remove-member [--workspace <name>] [--username <username>]
```

**Flags**

* `--workspace` (string, optional): Name or ID of workspace
* `--username` (string, optional): Username or ID of user to remove

**Examples**

```sh
# Remove a member
tessl workspace remove-member --workspace myworkspace --username johnsmith

# Interactive mode
tessl workspace remove-member
```

### tessl workspace list-members

List all members of a workspace.

**Usage**

```sh
tessl workspace list-members [<name>]
```

**Arguments**

* `name` (string, optional): The name or ID of the workspace. If omitted, you'll be prompted.

**Examples**

```sh
# List members of a workspace
tessl workspace list-members myworkspace

# Interactive mode
tessl workspace list-members
```

### tessl workspace archive

Archive a workspace. An archived workspace won't be available to publish to or read from, but can be unarchived later.

**Usage**

```sh
tessl workspace archive --reason <text> [<name>]
```

**Flags**

* `--reason` (string, required): Reason for archiving the workspace

**Arguments**

* `name` (string, optional): The name or ID of the workspace. If omitted, you'll be prompted.

**Notes**

* Archiving is a safer alternative to deleting, as archived workspaces can be restored
* Use `tessl workspace unarchive` to restore an archived workspace

**Examples**

```sh
# Archive a workspace with a reason
tessl workspace archive --reason "deprecated" myworkspace

# Interactive mode
tessl workspace archive --reason "no longer in use"
```

### tessl workspace unarchive

Unarchive an archived workspace, making it active again.

**Usage**

```sh
tessl workspace unarchive <name>
```

**Arguments**

* `name` (string, required): The name or ID of the workspace.

**Examples**

```sh
# Unarchive a workspace
tessl workspace unarchive myworkspace
```

***

## Configuration management

### tessl config get

Get a configuration value or show all configuration.

**Usage**

```sh
tessl config get [<key>]
```

**Arguments**

* `key` (string, optional): Configuration key to get. If omitted, shows all configuration.

**Examples**

```sh
# Show all configuration
tessl config get

# Get a specific configuration value
tessl config get shareUsageData
```

### tessl config set

Set a configuration value.

**Usage**

```sh
tessl config set <key> <value>
```

**Arguments**

* `key` (string, required): Configuration key to set. Supported values: `shareUsageData`, `termsAcceptedAt`, `evalDefaultModelNoticeShownAt`, `evalDefaultModelNoticeModel`, `agents`
* `value` (string, required): Configuration value to set

**Examples**

```sh
# Set a configuration value
tessl config set shareUsageData false
```

### tessl config list

List all configuration values.

**Usage**

```sh
tessl config list [<key>]
```

**Arguments**

* `key` (string, optional): Configuration key to list. If omitted, lists all configuration.

**Notes**

* Similar to `tessl config get` but specifically for listing configuration values

**Examples**

```sh
# List all configuration
tessl config list

# List a specific configuration key
tessl config list shareUsageData
```

### tessl config add

Add one or more values to a configuration array.

**Usage**

```sh
tessl config add <key> <value>...
```

**Arguments**

* `key` (string, required): Configuration key for the array
* `value` (string, required, repeatable): One or more values to add to the array

**Notes**

* Use this command to add values to array-type configuration settings
* Can specify multiple values in a single command

**Examples**

```sh
# Add a single value to an array configuration
tessl config add agents cursor

# Add multiple values to an array configuration
tessl config add agents cursor claude-code
```

### tessl config remove

Remove a value from a configuration array.

**Usage**

```sh
tessl config remove <key> <value>
```

**Arguments**

* `key` (string, required): Configuration key for the array
* `value` (string, required): Value to remove from the array

**Notes**

* Use this command to remove values from array-type configuration settings
* Only removes the specified value, not the entire configuration key

**Examples**

```sh
# Remove a value from an array configuration
tessl config remove agents cursor
```

***

## Diagnostics and utilities

### tessl doctor

Run authentication and manifest diagnostics to troubleshoot issues.

**Usage**

```sh
tessl doctor [--json]
```

**Flags**

* `--json` (boolean, optional): Output diagnostics as JSON for programmatic processing

**Examples**

```sh
# Run diagnostics with human-readable output
tessl doctor

# Output diagnostics as JSON
tessl doctor --json
```

### tessl feedback

Send feedback to the Tessl team.

**Usage**

```sh
tessl feedback [<message>]
```

**Arguments**

* `message` (string, optional): Feedback message to send. If omitted, you'll be prompted interactively.

**Examples**

```sh
# Send feedback directly
tessl feedback "Great tool! Would love to see Python support."

# Interactive feedback
tessl feedback
```

***

## CLI self-management

### tessl cli update

Update the CLI to the latest or specified version.

**Usage**

```sh
tessl cli update [--target <version>] [--channel <name>] [--dry-run]
```

**Flags**

* `--target` / `-t` (string, optional): Target version to update to (example: v1.0.0)
* `--channel` / `-c` (string, optional): Release channel to switch to. Supported values: `latest`, `beta`
* `--dry-run` (boolean, optional): Show what would be run without executing the update

**Examples**

```sh
# Update to the latest version
tessl cli update

# Update to a specific version
tessl cli update --target v1.0.0

# Switch to the beta release channel
tessl cli update --channel beta

# Preview update without executing
tessl cli update --dry-run
```

***

## API key management

### tessl api-key create

Create an API key for a workspace.

**Usage**

```sh
tessl api-key create [--workspace <name>] [--name <name>] [--role <role>] [--expiry-date <date>]
```

**Flags**

* `--workspace` (string, optional): Name or ID of workspace
* `--name` (string, optional): Name for the API key
* `--role` (string, optional): Role to assign. Supported values: `member`, `publisher`, `manager`, `owner`
* `--expiry-date` (string, optional): Expiry date in ISO 8601 format (example: 2027-12-31T00:00:00Z). Defaults to 30 days from creation

**Examples**

```sh
# Create an API key interactively
tessl api-key create

# Create an API key with all details specified
tessl api-key create --workspace engteam --name "ci-key" --role publisher --expiry-date 2027-12-31T00:00:00Z
```

### tessl api-key list

List API keys for a workspace.

**Usage**

```sh
tessl api-key list [--workspace <name>]
```

**Flags**

* `--workspace` (string, optional): Name or ID of workspace

**Examples**

```sh
# List API keys interactively
tessl api-key list

# List API keys for a specific workspace
tessl api-key list --workspace engteam
```

### tessl api-key delete

Delete an API key from a workspace.

**Usage**

```sh
tessl api-key delete [--workspace <name>] [--yes] [<api-key-id>]
```

**Flags**

* `--workspace` (string, optional): Name or ID of workspace
* `--yes` / `-y` (boolean, optional): Skip confirmation prompt and delete immediately

**Arguments**

* `api-key-id` (string, optional): ID of the API key to delete. If omitted, you'll be prompted.

**Examples**

```sh
# Delete an API key interactively
tessl api-key delete

# Delete a specific API key
tessl api-key delete --workspace engteam <api-key-id>
```

***

## Environment management

An environment is a named, workspace-scoped set of variables that a scheduled run, a launch, or a cloud run executes inside. Its values are sealed and write-only: you can set and replace them, but never read them back. Use an environment to supply the GitHub token, API keys, and any other credentials a run needs.

For what belongs in an environment and how runs consume it, see [Environments](/automations/environments.md).

{% hint style="info" %}
`tessl env` is a short alias for `tessl environment`. A scheduled run cannot mint its own GitHub token, so include a `GITHUB_TOKEN` (or `GH_TOKEN`) in the environment for any schedule that checks out a repository or opens pull requests.
{% endhint %}

### tessl environment create

Create an environment for a workspace.

**Usage**

```sh
tessl environment create [--workspace <name>] [--env-file <path>] [--mcp-server <name>] [--github-access <none|read|write>] <name>
```

**Arguments**

* `name` (string, required): Name for the environment.

**Flags**

* `--workspace` (string, optional): Name or ID of workspace.
* `--env-file` (string, optional): Path to a `.env` file with environment variables.
* `--mcp-server` (string, optional, repeatable): Name of a workspace MCP server to configure.
* `--github-access` (`none`, `read`, or `write`, optional): GitHub access granted to runs that use this environment. The default is `read`.

`none` mints no GitHub credential, so the run must bring its own token. `read` can clone the repository but cannot push. `write` can push branches and open pull requests; a person remains responsible for reviewing the changes and deciding whether to merge them.

**Examples**

```sh
# Create an environment and load its values from a .env file
tessl environment create production --env-file production.env

# Create an environment in a specific workspace
tessl environment create production --workspace engteam --env-file production.env

# Wire workspace MCP servers into the environment
tessl environment create production --env-file production.env --mcp-server linear --mcp-server slack

# Create an environment whose runs can push branches and open pull requests
tessl environment create production --env-file production.env --github-access write
```

### tessl environment list

List environments for a workspace.

**Usage**

```sh
tessl environment list [--workspace <name>] [--json]
```

**Flags**

* `--workspace` (string, optional): Name or ID of workspace.
* `--json` (boolean, optional): Output as JSON.

**Examples**

```sh
# List environments in the resolved workspace
tessl environment list

# List environments in a specific workspace
tessl environment list --workspace engteam

# Output as JSON
tessl environment list --json
```

### tessl environment view

View metadata for an environment.

**Usage**

```sh
tessl environment view [--workspace <name>] [--json] <name>
```

**Arguments**

* `name` (string, required): Name or ID of the environment to view.

**Flags**

* `--workspace` (string, optional): Name or ID of workspace.
* `--json` (boolean, optional): Output as JSON.

**Notes**

* This shows metadata only, such as the variable names, GitHub access, and MCP servers wired in. Sealed values are write-only and are never returned.

**Examples**

```sh
# View an environment
tessl environment view production

# View an environment as JSON
tessl environment view production --json
```

### tessl environment update

Update an environment for a workspace.

**Usage**

```sh
tessl environment update [--workspace <name>] [--env-file <path>] [--mcp-server <name>] [--github-access <none|read|write>] [--clear-mcp-servers] <name>
```

**Arguments**

* `name` (string, required): Name or ID of the environment to update.

**Flags**

* `--workspace` (string, optional): Name or ID of workspace.
* `--env-file` (string, optional): Path to a `.env` file with environment variables.
* `--mcp-server` (string, optional, repeatable): Name of a workspace MCP server to configure.
* `--github-access` (`none`, `read`, or `write`, optional): GitHub access granted to runs that use this environment.
* `--clear-mcp-servers` (boolean, optional): Remove all MCP servers wired into this environment.

`none` mints no GitHub credential, so the run must bring its own token. `read` can clone the repository but cannot push. `write` can push branches and open pull requests.

**Notes**

* `--env-file` is required unless at least one `--mcp-server` or `--github-access` is provided. A metadata-only update with no `--env-file` changes just the metadata and leaves every stored value untouched. Passing `--env-file` replaces the sealed values instead: the env file becomes the complete set, so it must include every credential you want to keep.
* `--clear-mcp-servers` always requires `--env-file`, including when it is combined with `--github-access` or `--mcp-server`, because clearing is treated as an update with no new MCP servers.

**Examples**

```sh
# Replace an environment's values from a .env file
tessl environment update production --env-file production.env

# Rewire which MCP servers the environment configures (stored values are kept)
tessl environment update production --mcp-server linear

# Allow runs to push branches and open pull requests (stored values are kept)
tessl environment update production --github-access write

# Remove every MCP server from the environment (credentials are replaced by the env file — include every value to keep)
tessl environment update production --clear-mcp-servers --env-file production.env
```

### tessl environment delete

Delete an environment from a workspace.

**Usage**

```sh
tessl environment delete [--workspace <name>] [name]
```

**Arguments**

* `name` (string, optional): Name or ID of the environment to delete. You are prompted when it is omitted.

**Flags**

* `--workspace` (string, optional): Name or ID of workspace.

**Examples**

```sh
# Delete an environment
tessl environment delete staging

# Delete an environment from a specific workspace
tessl environment delete staging --workspace engteam
```

***

## Model Context Protocol (MCP)

### tessl mcp start

Start the Tessl MCP (Model Context Protocol) server for integration with AI coding agents.

**Usage**

```sh
tessl mcp start
```

### tessl mcp proxy

Bridge a coding agent to a workspace MCP server through the Tessl MCP gateway. Starts a stdio MCP proxy that forwards JSON-RPC messages to a workspace-registered upstream MCP server, authenticating to the gateway with your Tessl credentials (`tessl login`) or `TESSL_TOKEN`. See [MCP gateway](/reference/mcp-gateway.md) for how to register the upstream server and wire the proxy into an agent or plugin `.mcp.json`.

**Usage**

```sh
tessl mcp proxy <workspace>/<mcp>
```

**Arguments**

* `workspace/mcp` (string, required): Slug of the workspace and the MCP server registered in that workspace's gateway (for example `engteam/linear`).

**Authentication**

* **Interactive use** — sign in once with `tessl login`; the proxy reuses the same credentials.
* **CI or other non-interactive contexts** — set `TESSL_TOKEN` to a Tessl API key for the workspace. See [`tessl api-key create`](#tessl-api-key-create).

**Examples**

```sh
# Proxy to an MCP server named `linear` in the `engteam` workspace
tessl mcp proxy engteam/linear
```

***

## Repository

### tessl repo select-commits

Browse recent commits in a repository and select which ones to evaluate. Used as the first step in [generating codebase scenarios](/improving-your-skills/evaluate-skill-quality-using-scenarios.md#generate-scenarios-from-your-codebase).

{% hint style="info" %}
This command is not listed in `tessl --help` but works when invoked directly.
{% endhint %}

**Usage**

```sh
tessl repo select-commits <org/repo> [flags]
```

**Arguments**

* `org/repo` (string, required): Repository in `org/repo` format

**Flags**

* `--keyword` (string, optional): Filter by commit message keyword
* `--author` (string, optional): Filter by author name
* `--since` / `--until` (string, optional): Date range in YYYY-MM-DD format
* `--count` / `-n` (number, optional): Number of commits to show (1–100)
* `--workspace` / `-w` (string, optional): Required outside interactive mode
* `--json` (boolean, optional): Output as JSON

**Prerequisite:** your GitHub or GitLab account must be connected in workspace settings. If it isn't, the error message includes a direct link to the settings page.

**Examples**

```sh
# Browse recent commits
$ tessl repo select-commits org/repo

# Filter by keyword and date range
$ tessl repo select-commits org/repo --keyword=feat --since=2026-01-01

# Show last 50 commits by a specific author
$ tessl repo select-commits org/repo --author="Alice" --count=50
```

***

## GitHub integration

Tessl Helper is a GitHub App your workspace installs. These commands mint short-lived installation tokens so CI steps and coding agents can act as the Tessl Helper bot without holding the App's private key.

A workspace can reach the Tessl Helper App on more than one GitHub account. Pass `--repo owner/name` to say which: the owner selects the installation to mint from, and the repository names limit what the token can reach. Without it, the most recently updated installation is used, which may not be the one that owns the repositories you want.

### tessl github token

Mint a short-lived GitHub installation token for the Tessl Helper bot and print it to stdout.

**Usage**

```sh
$ tessl github token [--workspace <name>] [--repo <owner/name>]...
```

**Flags**

* `--workspace` (string, optional): Name or ID of workspace
* `--repo` (string, optional, repeatable): Scope the token to a repository and select its installation by owner, in `owner/name` form. All values must share one owner, since a token is minted against a single installation.

**Notes**

* The token is written to stdout so it can be captured directly, for example `GH_TOKEN=$(tessl github token ...)`. The expiry is written to stderr, so it does not pollute that capture.
* The minted token is a GitHub App installation token, not a user token. Installation-scoped endpoints such as `/installation/repositories` work; user-scoped endpoints such as `gh org list` fail.
* Without `--repo`, the token covers everything the selected installation can reach.

**Examples**

```sh
# Mint a token scoped to one repository
$ tessl github token --workspace engteam --repo my-org/my-repo

# Scope to several repositories owned by the same account
$ tessl github token --workspace engteam --repo my-org/api --repo my-org/web

# Capture the token for a single command
$ GH_TOKEN=$(tessl github token --workspace engteam --repo my-org/my-repo) gh api /installation/repositories
```

### tessl github setup-auth

Configure `gh` and `git` on this machine to act as the Tessl Helper bot, so subsequent commands authenticate without a token in the environment.

**Usage**

```sh
$ tessl github setup-auth [--workspace <name>] [--repo <owner/name>]... [--force] [--auto-refresh] [--refresh-interval-seconds <seconds>]
```

**Flags**

* `--workspace` (string, optional): Name or ID of workspace
* `--repo` (string, optional, repeatable): Scope the token to a repository and select its installation by owner, in `owner/name` form. All values must share one owner.
* `--force` (boolean, optional): Overwrite an existing `gh`/`git` auth configuration. Without it, the command stops rather than replacing one already in place.
* `--auto-refresh` (boolean, optional): Spawn a background process that re-mints the token periodically, for steps that outlive a single token.
* `--refresh-interval-seconds` (number, optional): How often that background process re-mints, in seconds. Defaults to 2700, which is 45 minutes.

**Notes**

* Signs in `gh` and sets a global git identity for the bot. This persists after the command exits, so prefer an ephemeral runner or container.
* Refuses to run when `gh` is already signed in or a global git identity is already set. Use `--force` to replace them.
* Clear `GH_TOKEN` and `GITHUB_TOKEN` first. `gh` prefers a token in the environment over the credential this writes.
* Without `--auto-refresh` the credential lasts until the expiry the command prints.
* With `--repo`, refreshes re-mint against the same owner and repositories. Without it, each refresh picks the most recently updated installation.

**Examples**

```sh
# Authenticate for one repository
$ tessl github setup-auth --workspace engteam --repo my-org/my-repo

# Long-running CI step, refreshing in the background
$ tessl github setup-auth --workspace engteam --repo my-org/my-repo --auto-refresh

# Replace an existing gh/git configuration
$ tessl github setup-auth --workspace engteam --repo my-org/my-repo --force
```

***

## Inventory

### tessl inventory import

Scan a GitHub account or org for installed skills and upload an inventory. Forked repos are skipped.

**Usage**

```sh
tessl inventory import [--org <account>] [--workspace <name>] [--repo <repo>]... [--ignore-repo <repo>]... [--dry-run <path>]
```

**Flags**

* `--org` (string, optional): GitHub account or org to scan. Prompted if omitted.
* `--workspace` (string, optional): Name or ID of workspace to upload to. Prompted if omitted.
* `--repo` (string, repeatable, optional): Limit scan to this repo (repeatable)
* `--ignore-repo` (string, repeatable, optional): Exclude this repo from the scan (repeatable)
* `--dry-run` (string, optional): Write inventory JSON to the given path instead of uploading

**Notes**

* `--org` and `--workspace` are prompted when omitted in interactive sessions, but required as flags in non-interactive environments (including with `--dry-run`)

**Examples**

```sh
# Scan an org and upload to a workspace
tessl inventory import --org my-github-org --workspace engteam

# Limit the scan to specific repositories
tessl inventory import --org my-github-org --workspace engteam --repo repo-a --repo repo-b

# Preview the inventory without uploading
tessl inventory import --org my-github-org --workspace engteam --dry-run ./inventory.json
```

***

## Scenario management

{% hint style="warning" %}
Scenario management and evals are in public beta. Workflows and output formats may change in upcoming releases.
{% endhint %}

Scenario commands generate and manage eval scenarios from real repository commits. For a full walkthrough, see [Prove a skill works using evaluation](/improving-your-skills/evaluate-skill-quality-using-scenarios.md).

### tessl scenario generate

Generate eval scenarios from a plugin or repository commits. Runs server-side — the CLI polls until complete. Ctrl-C detaches without cancelling; check progress with `tessl scenario list`.

**Alias:** `tessl scenarios generate`

**Usage**

```sh
tessl scenario generate [--commits <hash1,hash2>] [--prs <id1,id2>] [--count <n>] [--workspace <name>] [--context <globs>] [--json] [--no-wait] <source>
```

**Arguments**

* `source` (string, required): plugin path or `org/repo` to generate scenarios from

**Flags**

* `--commits` (string, optional): Comma-separated commit hashes to generate scenarios from (repo only)
* `--prs` (string, optional): Comma-separated PR numbers to resolve as commit ranges (repo only)
* `--count` / `-n` (number, optional): Number of new scenarios to add (plugin only)
* `--context` (string, optional): Glob patterns for context files to exclude from baseline, comma-separated (repo only). These patterns are stored in each generated `scenario.json` as `fixture.exclude` — they are stripped for the baseline eval variant and injected back for the with-context variant. Defaults to `*.mdc`, `*.md`, `tile.json`, `.tessl-plugin/plugin.json`, `tessl.json`, `.tessl/` when omitted.
* `--workspace` / `-w` (string, optional): Workspace name or ID (repo only). Required outside interactive mode.
* `--json` (boolean, optional): Output as JSON
* `--wait` / `--no-wait` (boolean, optional): Wait for the generation to finish before returning (default: wait when interactive; a non-interactive run, such as CI, submits and returns without waiting; use `--no-wait` to force that anywhere, then reconnect with `tessl scenario view`). `--json` on its own also detaches; pass `--wait --json` to poll to completion and still get JSON.

**Examples**

```sh
# Generate scenarios for two commits
$ tessl scenario generate org/repo --commits=abc123,def456

# Generate scenarios from PRs
$ tessl scenario generate org/repo --prs=42,43

# Generate scenarios from a plugin
$ tessl scenario generate ./my-plugin --count=5

# Specify context file patterns
$ tessl scenario generate org/repo --commits=abc123 --context="*.mdc,*.md"

# Non-interactive with workspace
$ tessl scenario generate org/repo --commits=abc123 --workspace=engteam
```

### tessl scenario list

List recent scenario generation runs in reverse chronological order.

**Alias:** `tessl scenarios list`

**Usage**

```sh
tessl scenario list [--mine] [--workspace <name>] [--limit <count>] [--status <status>] [--json]
```

**Flags**

* `--mine` (boolean, optional): Only show generation runs created by you
* `--workspace` / `-w` (string, optional): Filter by workspace name
* `--limit` (number, optional): Maximum number of runs to display (default: 20)
* `--status` (string, optional): Filter by status. Supported values: `pending`, `in_progress`, `completed`, `failed`
* `--json` (boolean, optional): Output as JSON

### tessl scenario view

Inspect a scenario generation run. Shows run metadata and a table of generated scenarios with titles and checklist item counts.

**Alias:** `tessl scenarios view`

**Usage**

```sh
tessl scenario view [--last] [--json] [<id>]
```

**Flags**

* `--last` (boolean, optional): View the most recent generation run
* `--json` (boolean, optional): Output as JSON

**Arguments**

* `id` (string, optional): Generation run ID. Either `id` or `--last` is required.

**Examples**

```sh
# View the most recent generation run
$ tessl scenario view --last

# View a specific run
$ tessl scenario view 019c4791-9eec-7458-b28a-6c94405a3d38
```

### tessl scenario download

Download generated scenarios to your local `evals/` folder.

**Alias:** `tessl scenarios download`

**Usage**

```sh
tessl scenario download [--output <dir>] [--strategy <strategy>] [--json] [--last] <id>...
```

**Flags**

* `--output` / `-o` (string, optional): Output directory (default: `evals`)
* `--strategy` / `-s` (string, optional): Write strategy: `merge` (default) adds new scenarios alongside existing ones; `replace` clears the directory first
* `--json` (boolean, optional): Output as JSON
* `--last` (boolean, optional): Download from the most recent generation run

**Arguments**

* `id` (string, required, repeatable): Generation IDs to download. Can specify multiple IDs. Either `id` or `--last` is required.

If the generation run is still in progress or pending, the command reports the status and exits.

**Downloaded structure:**

```
evals/
  <7-char-hash>-<slug>/
    task.md          ← task brief shown to the agent
    criteria.json    ← weighted checklist rubric
    scenario.json    ← fixture with repo URL, commit ref, and context exclude patterns
```

**Examples**

```sh
# Download from the most recent generation run
$ tessl scenario download --last

# Download to a custom directory, replacing existing scenarios
$ tessl scenario download --last --output=my-evals --strategy=replace

# Download a specific run
$ tessl scenario download 019c4791-9eec-7458-b28a-6c94405a3d38
```

***

## Evaluations

For more information on workflows and usage, see [Prove a skill works using evaluation](/improving-your-skills/evaluate-skill-quality-using-scenarios.md).

### tessl eval run

Run evals from a scenarios directory. The context under test, if any, comes from `--context`; with no context, the run is the baseline variant alone (see Notes).

* **Codebase eval**: source directory contains `scenario.json` fixtures → runs with smart defaults (agent `claude`, model `deepseek-v4-flash`, context pattern from `fixture.exclude`, context ref `infer`)
* **Plugin eval** — source contains `.tessl-plugin/plugin.json` → runs the plugin's own evals. Pass the plugin root directory (the directory that contains `.tessl-plugin/`, not `.tessl-plugin/` itself).

Pointing at a plugin directory is shorthand: `tessl eval run ./my-plugin` expands to `tessl eval run ./my-plugin/evals --context ./my-plugin` — the plugin's `evals/` as the scenarios, the plugin itself as the context. An explicit `--context` opts out of the shorthand.

**Usage**

```sh
tessl eval run [--agent <agent>] [--model <model>] [--scorer-agent <agent>] [--scorer-model <model>] [--context <source>] [--context-commit <ref>] [--skill <name>]... [--skip-baseline] [--runs <count>] [--label <text>] [--env-file <path>] [--skip-forced-context-activation] [--skip-scoring] [--force] [--quality-check] [--list-agents] [--yes] [--json] [--no-wait] [<source>]
```

**Flags**

* `--agent` (string, optional): Agent to run with (e.g. `claude`). May be passed alone or together with `--model`. Run `tessl eval run --list-agents` to see supported values and combinations. Default pair when neither override is supplied: `claude` / `deepseek-v4-flash`
* `--model` (string, optional): Model to run with (e.g. `claude-sonnet-4-5`). May be passed alone or together with `--agent`. Run `tessl eval run --list-agents` to see supported values and combinations. Default pair when neither override is supplied: `claude` / `deepseek-v4-flash`
* `--scorer-agent` (string, optional): Override the agent used for the scoring step; the solver agent is unchanged. May be passed alone or together with `--scorer-model`.
* `--scorer-model` (string, optional): Override the model used for the scoring step; the solver model is unchanged. May be passed alone or together with `--scorer-agent`.
* `--context` (string, optional): Context to test — a local path (a plugin directory, or a file/glob), or a published `workspace/plugin@version`. Adds the with-context variant alongside the baseline. See the examples below.
* `--context-commit` (string, optional): Commit, branch, or tag to source a local `--context` from instead of the working tree. Requires `--context`.
* `--skill` (string, optional, repeatable): Narrow a local plugin `--context` to specific skills. Local plugin contexts only — not valid with a published context.
* `--skip-baseline` (boolean, optional): Skip the always-on baseline variant, running only the with-context variant.
* `--runs` / `-n` (number, optional): Number of times to repeat each agent configuration.
* `--label` / `-l` (string, optional): A short description to attach to this eval run. Visible in `tessl eval list` and the Tessl web UI.
* `--env-file` (string, optional): Path to a `.env` file whose variables are encrypted client-side and made available to the run's sandbox environment.
* `--skip-forced-context-activation` (boolean, optional): Omit the prompt line that tells the agent to use the injected context, so the run measures whether the agent activates the context on its own. Default off (the agent is told to use the context).
* `--skip-scoring` (boolean, optional): Skip the rubric scoring step. Default off (runs are scored).
* `--force` / `-f` (boolean, optional): Re-run all evals, including previously solved cases.
* `--quality-check` (boolean, optional): Exclude misleading scenarios (low feasibility, rubric leakage, low value) from the run. Excluded scenarios appear in `tessl eval view` under a `✗ Excluded by quality check` line.
* `--list-agents` (boolean, optional): Print the supported `--agent` / `--model` values, then exit without running an eval. Combine with `--json` for a machine-readable shape.
* `--yes` / `-y` (boolean, optional): Skip the confirmation prompt for large-scale eval runs.
* `--json` (boolean, optional): Output eval run IDs as JSON. On its own it detaches and prints the run ids immediately without polling; pass `--wait --json` to poll to completion and emit each run id with its final status.
* `--wait` / `--no-wait` (boolean, optional): Wait for the run to finish before returning (default: wait when interactive; use `--no-wait` to submit and return the run ids immediately, then reconnect with `tessl eval view`). `--json` on its own detaches; pass `--wait --json` to poll to completion and still get JSON.

**Arguments**

* `source` (string, optional): Path to a plugin folder or scenarios directory. Defaults to the current directory if omitted.

**Notes**

* A run has up to two variants. The **baseline** solves each scenario as authored; the **with-context** variant solves it with the injected context added on top. Baseline is not an empty run — each scenario keeps any fixtures it defines; no context is injected on top. The with-context variant runs when context is specified. Baseline runs by default; use `--skip-baseline` to run only the with-context variant.
* Eval runs require this directory to be linked to a Tessl project first, and always run under that project's workspace. See [Projects overview](/projects/overview.md).
* To measure whether the agent activates the injected context on its own, with no rubric scoring, combine both flags: `--skip-forced-context-activation --skip-scoring`.
* Ctrl-C detaches without cancelling: runs continue server-side. The CLI prints each run ID.
* `--no-wait` submits the runs and returns their ids without polling; reconnect later with `tessl eval view`. `--json` alone also detaches, so pass `--wait --json` when a pipeline needs to block for the final per-run status.

**Agent and model:** `--agent` and `--model` are independent overrides; supply either or both. Run `tessl eval run --list-agents` for the supported combinations.

**Examples**

```sh
# Run a plugin's evals (shorthand for ./my-plugin/evals --context ./my-plugin)
$ tessl eval run .

# ...or point at the plugin by path
$ tessl eval run ./my-plugin

# Run a scenarios directory directly — baseline only, no context
$ tessl eval run ./evals/

# Force re-run all evals
$ tessl eval run --force ./my-plugin

# Run with a specific agent and model
$ tessl eval run ./evals/ --agent claude --model claude-sonnet-4-6

# List the supported --agent / --model values
$ tessl eval run --list-agents

# Skip scenarios the LLM judge flags as misleading
$ tessl eval run ./my-plugin --quality-check

# Measure context activation only: don't force the agent to use the context, and skip scoring
$ tessl eval run ./my-plugin --skip-forced-context-activation --skip-scoring

# Test a published context against a scenarios directory
$ tessl eval run ./evals/ --context engteam/my-plugin@1.0.0

# Test a local plugin directory as the context
$ tessl eval run ./evals/ --context ./my-plugin

# Test a glob of local files as the context
$ tessl eval run ./evals/ --context 'src/**/*.knowledge.md'

# Test a local context as it was at a specific commit
$ tessl eval run ./evals/ --context ./my-skill --context-commit HEAD

# Run only the with-context variant (skip the baseline)
$ tessl eval run ./my-plugin --skip-baseline

# Label a run for easier identification later
$ tessl eval run ./my-plugin --label "testing claude-opus-4-6"

# Pass secrets into the sandbox via an env file
$ tessl eval run ./my-plugin --env-file ./secrets.env
```

### tessl eval list

List recent eval runs in reverse chronological order.

**Usage**

```sh
tessl eval list [--json] [--limit <count>] [--mine] [--workspace <name>] [--plugin <name>] [--status <status>] [--context-type <type>]
```

**Flags**

* `--json` (boolean, optional): Output results as JSON
* `--limit` (number, optional): Maximum number of eval runs to display (default: 20)
* `--mine` (boolean, optional): Only show eval runs created by you
* `--workspace` / `-w` (string, optional): Filter by workspace name
* `--plugin` (string, optional): Filter by plugin name
* `--status` (string, optional): Filter by run status. Supported values: `pending`, `completed`, `failed`
* `--context-type` (string, optional): Filter by eval type. Supported values: `plugin`, `plugin-directory`, `files`, `commit`, `no-context`

**Notes**

* The output table includes ID, Type, Subject, Status, Created By, and Created columns
* The Type column reflects the context fixture used by the run:
  * `plugin` → `Plugin`
  * `plugin-directory` → `Plugin directory`
  * `files` (alias for the `directory` fixture) → `Selected files` when globs filter it to a subset, otherwise `Directory`
  * `commit` → `Commit`
* The Subject column formats entries by fixture: `plugin` runs as `workspace/plugin@version` (or just `workspace/plugin` when no version is set); `plugin-directory` and `files` as the source path; `commit` as `org/repo@ref`
* `--context-type no-context` filters to baseline runs that did not inject any context fixture
* `files` is the documented spelling of the canonical `directory` fixture — both names accepted

**Examples**

```sh
# List all recent eval runs
tessl eval list

# List only completed runs
tessl eval list --status completed

# List your runs in a specific workspace
tessl eval list --mine --workspace myteam

# Output as JSON
tessl eval list --json
```

### tessl eval view

View results for a specific eval run.

**Usage**

```sh
tessl eval view [--json] [--last] [<id>]
```

**Flags**

* `--json` (boolean, optional): Output results as JSON
* `--last` (boolean, optional): View results for the most recent eval run

**Arguments**

* `id` (string, optional): Eval run ID

**Examples**

```sh
# View a specific eval run
tessl eval view 019c4791-9eec-7458-b28a-6c94405a3d38

# View the most recent eval run
tessl eval view --last

# View results as JSON
tessl eval view --json 019c4791-9eec-7458-b28a-6c94405a3d38
```

### tessl eval retry

Re-run a failed eval run.

**Usage**

```sh
tessl eval retry [--json] [--last] [<id>]
```

**Flags**

* `--json` (boolean, optional): Output as JSON
* `--last` (boolean, optional): Retry the most recent eval run

**Arguments**

* `id` (string, optional): Eval run ID to retry. Either `id` or `--last` is required.

**Examples**

```sh
# Retry a specific eval run
tessl eval retry 019c4791-9eec-7458-b28a-6c94405a3d38

# Retry the most recent eval run
tessl eval retry --last
```

### tessl eval lint

Validate eval scenario structure. This checks the shape of the scenarios, not skill quality.

**Usage**

```sh
tessl eval lint [source]
```

**Arguments**

* `source` (string, optional): Path to a plugin folder or a scenarios directory.

**Notes**

* A scenario directory is recognized by the presence of `task.md`. Directories without `task.md` are skipped rather than reported as invalid, so an intended scenario that is missing the file passes lint silently. Each recognized scenario directory should contain a non-empty `task.md` and a `criteria.json` weighted checklist rubric.
* `scenario.json`, a `resources/` directory, and `setup.sh` are optional. `resources/` is included automatically and `setup.sh` runs automatically when present.
* Run `tessl eval lint --help` for the full `criteria.json` and `scenario.json` field reference, including the supported fixture types.

**Examples**

```sh
# Lint scenarios in the current directory
tessl eval lint

# Lint a specific plugin folder
tessl eval lint ./my-plugin

# Lint a scenarios directory
tessl eval lint ./evals
```

***

## Agent

The `tessl agent` command runs the Tessl agent directly from the CLI. The `tessl agent mcp` subcommands manage MCP server entries used by the Tessl agent.

### tessl agent

Run the Tessl agent in an interactive or non-interactive session.

**Usage**

```sh
tessl agent [flags] [prompt]
```

**Arguments**

* `prompt` (string, optional): Prompt to send to the agent.

**Flags**

* `--permission-mode` (string, optional): Permission mode for this run (supported values: `ask`, `accept-edits`, `auto`, `yolo`) (default: `auto`)
* `--yolo` (boolean, optional): Auto-approve every permission check (alias for `--permission-mode yolo`)
* `--print` / `-p` (boolean, optional): Run non-interactively, print the response, and exit
* `--output` (string, optional): Output format when `--print` is set (supported values: `text`, `json`) (default: `text`)
* `--message` (string, optional): Initial user message to send to the agent
* `--model` (string, optional): Model ID to use (example: `anthropic/claude-opus-4-6`)
* `--thinking` (string, optional): Thinking level (supported values: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`)
* `--continue` / `-c` (boolean, optional): Resume the most recent session for this directory
* `--resume` / `-r` (string, optional): Resume a specific session by ID (uuid or unambiguous prefix)
* `--no-session` (boolean, optional): Disable agent session persistence
* `--session-dir` (string, optional): Agent session storage directory
* `--ephemeral` (boolean, optional): Use in-memory agent settings for this run only
* `--tools` (string, optional): Comma-separated tool allowlist (example: `read,grep,find,ls`)
* `--no-builtin-tools` (boolean, optional): Disable built-in tools but keep extension tools enabled
* `--no-tools` (boolean, optional): Disable all tools
* `--extension` (string, repeatable, optional): Extension source to load (example: `./my-extension.ts` or `npm:my-ext`)
* `--no-extensions` (boolean, optional): Disable extension discovery while keeping explicit `--extension`
* `--skill` (string, repeatable, optional): Skill path to load
* `--no-skills` (boolean, optional): Disable skill discovery while keeping explicit `--skill`
* `--prompt-template` (string, repeatable, optional): Prompt template path to load
* `--no-prompt-templates` (boolean, optional): Disable prompt template discovery while keeping explicit `--prompt-template`
* `--theme` (string, repeatable, optional): Theme path to load
* `--no-themes` (boolean, optional): Disable theme discovery while keeping explicit `--theme`
* `--no-context-files` (boolean, optional): Disable AGENTS.md and CLAUDE.md discovery
* `--no-memory` (boolean, optional): Disable `.tessl/memory` injection and updates

**Notes**

* Uses Tessl-managed model settings and shared Tessl authentication. `tessl login` and `/login` inside the agent are equivalent.
* Use `--print` / `-p` for non-interactive use (combine with `--output json` for structured output).
* Use `--continue` / `-c` to resume the most recent session for the current directory, or `--resume` / `-r <id>` to reopen a specific session.

**Examples**

```sh
# Start an interactive agent session
tessl agent

# Send a one-shot prompt and print the response
tessl agent --print "Summarize the recent changes"

# Run non-interactively with JSON output
tessl agent --print --output json "List the files changed in the last commit"

# Resume the most recent session
tessl agent --continue

# Use a specific model
tessl agent --model anthropic/claude-opus-4-6

# Run in yolo mode (auto-approve all permissions)
tessl agent --yolo
```

### tessl agent mcp add

Add or update an MCP server entry in the agent's MCP configuration.

**Usage**

```sh
tessl agent mcp add [--scope <project|global>] [--url <url>] [--env KEY=VALUE]... [--header Header: value]... <name> [-- <command> [args...]]
```

**Arguments**

* `name` (string, required): MCP server name.

**Flags**

* `--scope` (string, optional): Config scope (supported values: `project`, `global`) (default: `project`). `project` writes to `.mcp.json` in the current directory; `global` writes to `~/.tessl/`.
* `--url` (string, optional): HTTP MCP server URL. Omit for stdio servers.
* `--env` / `-e` (string, repeatable, optional): Environment variable for stdio servers in `KEY=VALUE` format.
* `--header` (string, repeatable, optional): HTTP header for HTTP servers in `Header: value` format.

**Notes**

* For stdio servers: omit `--url` and pass the server command after `--` (e.g., `-- npx my-server`).
* For HTTP servers: pass `--url`. Use `--header` for authentication headers.
* If the server name already exists, it is overwritten.

**Examples**

```sh
# Add a stdio MCP server
tessl agent mcp add my-server -- npx my-mcp-server

# Add a stdio server with environment variables
tessl agent mcp add my-server --env API_KEY=abc123 -- npx my-mcp-server

# Add an HTTP MCP server
tessl agent mcp add my-server --url https://mcp.example.com

# Add an HTTP server with an authentication header
tessl agent mcp add my-server --url https://mcp.example.com --header "Authorization: Bearer token"

# Add to global scope (available across all projects)
tessl agent mcp add my-server --scope global -- npx my-mcp-server
```

### tessl agent mcp get

Show a configured MCP server entry.

**Usage**

```sh
tessl agent mcp get [--json] <name>
```

**Arguments**

* `name` (string, required): MCP server name.

**Flags**

* `--json` (boolean, optional): Emit the resolved server entry as JSON.

### tessl agent mcp list

List all configured MCP servers.

**Usage**

```sh
tessl agent mcp list [--scope <project|global>] [--json]
```

**Flags**

* `--scope` (string, optional): Config scope to list (supported values: `project`, `global`). When omitted, servers from all scopes are listed.
* `--json` (boolean, optional): Output as JSON.

### tessl agent mcp remove

Remove an MCP server entry from the agent's MCP configuration.

**Usage**

```sh
tessl agent mcp remove [--scope <project|global>] <name>
```

**Arguments**

* `name` (string, required): MCP server name.

**Flags**

* `--scope` (string, optional): Config scope to remove from (supported values: `project`, `global`) (default: `project`)

***

## Change

The `tessl change` family assesses and verifies the current diff against your team's policies. Commands require a checked-in configuration and produce structured output suitable for CI use.

### tessl change risk

Assess the risk of the current PR/diff against the team's checked-in risk policy and decide whether it requires human review.

**Usage**

```sh
tessl change risk [--base <ref>] [--output <path>] [--fail-if-review-required] [--json]
```

**Flags**

* `--base` (string, optional): Diff base ref (default: the `baseRef` in the risk config, or `origin/main`)
* `--output` (string, optional): Write results to a file
* `--fail-if-review-required` (boolean, optional): Exit non-zero when scoring succeeds but human review is required
* `--json` (boolean, optional): Output as JSON

**Notes**

* Requires a risk policy under `.github/pr-review-gate`. Run `tessl change risk init` first if it is missing.
* Scoring is split into deterministic git measurements, an advisory agent risk judgment, strict validation, and a deterministic gate decision.
* Tooling failures (missing config, failed agent call, malformed output) are reported as distinct errors rather than a "human review required" result.

**Examples**

```sh
# Assess risk for the current diff
tessl change risk

# Assess risk and exit non-zero if human review is required (for CI use)
tessl change risk --fail-if-review-required

# Write results to a file as JSON
tessl change risk --output risk.json --json
```

### tessl change risk init

Write PR review-gate starter files under `.github/pr-review-gate`.

**Usage**

```sh
tessl change risk init [--policy <starter>] [--force] [--json]
```

**Flags**

* `--policy` (string, optional): Starter policy to write. Supported values:
  * `conservative-starter`: strict — clears only clearly surface-level changes; requires review for real behavior changes, sensitive paths, migrations, auth, architecture, and policy/config changes.
  * `official-review-policy-parity`: permissive — requires human review only when the official written review policy requires it.
  * If omitted, prompts interactively.
* `--force` (boolean, optional): Overwrite existing files.
* `--json` (boolean, optional): Output as JSON.

**Notes**

* Writes `config.json`, `policy.md`, and `prompt.md` under `.github/pr-review-gate`.
* Existing files are left untouched unless `--force` is passed.
* Read and edit the generated policy and config before relying on the gate.
* This command does not change branch protection rules or create any GitHub workflow.

**Examples**

```sh
# Write starter files interactively
tessl change risk init

# Write the conservative starter without prompting
tessl change risk init --policy conservative-starter

# Overwrite existing files
tessl change risk init --policy conservative-starter --force
```

### tessl change verify

Verify changed files against configured verifiers.

**Usage**

```sh
tessl change verify [--json] [--all] [--recursive] [--base <ref>] [--changed-files-mode introduced-only|whole-file] [--group <name>] [--verifier <id>]... [--include <glob>]... [--exclude <glob>]... [--max-concurrency <n>] [--max-calls <n>] [--sample <n>] [--batch-timeout <s>] [--dry-run] [--show-files] [--include-disabled] [--output <path>] [--report-json <path>] [--no-cache] [--refresh-cache] [--verbose] [--strict-coverage] [--fail-on-warn] [--github] [<path>...]
```

**Arguments**

* `path` (string, repeatable, optional): Optional path scope (file or directory) to verify

**Flags**

* `--json` (boolean, optional): Output as JSON
* `--all` (boolean, optional): Verify every matching file, not just the diff
* `--recursive` (boolean, optional): Verify each configured root from this project plus its child manifests
* `--base` (string, optional): Diff base ref (default: `main`)
* `--changed-files-mode` (string, optional): How to judge changed files. Supported values: `introduced-only` (gates on diff-attributable violations), `whole-file` (judges each changed file in full) (default: `introduced-only`)
* `--group` (string, optional): Run only this verifier group from the manifest
* `--verifier` (string, repeatable, optional): Run only this verifier id (repeatable)
* `--include` (string, repeatable, optional): Override include glob (repeatable)
* `--exclude` (string, repeatable, optional): Override exclude glob (repeatable)
* `--max-concurrency` (number, optional): Cap parallel judge calls (default: 48)
* `--max-calls` (number, optional): Refuse broad runs above this many judge calls (default: 300)
* `--sample` (number, optional): Run a deterministic sample of verifier targets
* `--batch-timeout` (number, optional): Abort the judge batch if it runs longer than this many seconds
* `--dry-run` (boolean, optional): Show what a verify run would do without spending judge calls
* `--show-files` (boolean, optional): Print the matched file list for each verifier (use with `--dry-run`)
* `--include-disabled` (boolean, optional): Also run groups marked `enabled=false`
* `--output` (string, optional): Write the report to a file instead of stdout
* `--report-json` (string, optional): Write the structured JSON report to a file, leaving stdout as-is. Uses the same shape as `--json` (a recursive run writes the per-root envelope). Combine with `--github` to write the report and emit annotations in one run
* `--no-cache` (boolean, optional): Skip the local result cache entirely (no reads, no writes)
* `--refresh-cache` (boolean, optional): Skip cache reads but save new results
* `--verbose` (boolean, optional): Show every considered file/verifier target
* `--strict-coverage` (boolean, optional): Stale `covered_by` links cause non-zero exit even when judges pass
* `--fail-on-warn` (boolean, optional): Treat warning verdicts as non-zero exit
* `--github` (boolean, optional): Emit GitHub Actions warning/error annotations for findings

**Examples**

```sh
# Verify the current diff against configured verifiers
tessl change verify

# Preview what a run would do without spending judge calls
tessl change verify --dry-run --show-files

# Verify only a specific group and emit GitHub annotations (for CI use)
tessl change verify --group my-group --github

# Write a machine-readable report for CI while still emitting annotations
$ tessl change verify --github --report-json verify-report.json
```

### tessl change verify suggest-scopes

Suggest repo-specific verifier scopes for a group.

**Usage**

```sh
tessl change verify suggest-scopes [--json] [--group <name>] [--heuristic] [--no-llm] [--apply] [--force]
```

**Flags**

* `--json` (boolean, optional): Output as JSON
* `--group` (string, optional): Suggest scopes only for this verifier group
* `--heuristic` (boolean, optional): Use the offline heuristic instead of the default LLM suggestion
* `--no-llm` (boolean, optional): Alias for `--heuristic`
* `--apply` (boolean, optional): Write suggestions into `tessl.json`
* `--force` (boolean, optional): Replace existing verifier-level overrides

### tessl change verify lint

Validate a verifier JSON file against the schema.

**Usage**

```sh
tessl change verify lint <verifier.json>
```

**Arguments**

* `verifier.json` (string, required): Path to the verifier JSON file to validate

***

## Code review

### tessl code review

Run a Tessl Code Review over a code change and print the result. `tessl code review` is shorthand for `tessl code review run`.

**Usage**

```sh
tessl code review [--profile <name-or-path>] [--skill <skill-ref>]... [--effort <level>] [--approver <login>]... [--pr <ref>] [--base <ref>] [--head <ref>] [--pr-fixture <path>] [--publish <comment|verdict>] [--json]
```

**Flags**

* `--profile` (string, optional): Review profile. Use the built-in `standard` profile (the default), or pass an explicit path to a repository-owned `.yml` or `.yaml` file.
* `--skill` (string, repeatable, optional): Reviewer lens: a local SKILL.md path or skill directory, an installed skill name, or a registry ref `workspace/plugin[@version]#skill-name`. Order is preserved, and a maximum of 8 lenses is supported. Passing `--skill` replaces the profile's default lens set entirely rather than adding to it.
* `--pr` (string, optional): Review a pull request by reference (number, URL, or provider ref) and capture its context. Mutually exclusive with `--base` and `--head`.
* `--base` (string, optional): Base ref of an explicit Git range to review. Defaults to the repository's own default branch when omitted. No pull request is required.
* `--head` (string, optional): Head ref of an explicit Git range to review. Defaults to the local working tree, including uncommitted changes, when omitted.
* `--pr-fixture` (string, optional): Replay a versioned pull-request fixture file instead of resolving a live pull request (experimental). Mutually exclusive with `--pr`, `--base`, and `--head`.
* `--effort` (string, optional): How hard each review lens thinks: `low`, `medium`, `high`, or `adaptive`. Applies to every lens, overriding any `effort` the profile sets. `adaptive` uses `medium` for a full review and `low` for a re-review; `low`, `medium`, and `high` stay fixed at that level. The built-in `standard` profile uses `adaptive`, so omitting `--effort` on a standard review already scales this way. Omit it and each lens uses its own `effort` where the profile gives it one, then the profile's `effort`, then the model's own default. Higher settings take longer.
* `--approver` (string, repeatable, optional): A comment-author login permitted to ask the review to approve the pull request instead of reviewing it, beyond the repository members who always may. The same allowlist also permits requesting a full re-review of the whole change (rather than the narrower incremental round), so a login named here gains both privileged intents, not just approval. Repository owners, members, and collaborators can already do both; a GitHub App cannot, because it comments with association `NONE` whatever its permissions, so name its `[bot]` login here to let it approve or request a full review. Capitalization does not matter. Omit it to name no extra login, which does not stop a member using either.
* `--publish` (string, optional): Publish the completed review to the pull request it reviewed. `comment` publishes a review that neither approves nor blocks. `verdict` publishes the verdict the review reached, approving when nothing requires changes and requesting changes otherwise. Applies to pull requests only, and cannot be combined with `--pr-fixture`.
* `--json` (boolean, optional): Output as JSON

**Notes**

* With no selection flags, the review auto-selects its subject: the current pull request in a supported CI environment, otherwise the complete local change. A local change is diffed against the repository's default branch, taken from the remote's recorded `origin/HEAD` and, in a clone that records none, from `origin/main` or `origin/master`. Where none of those resolves, the command says so rather than guessing, and `--base` names the ref to use instead.
* A local commit range with nothing in it is not reviewed. On a clean, up-to-date checkout the command exits successfully reporting that there are no changes to review, having run no lens, rather than reporting an approval it has no change to base one on. A working-tree change and a pull request are always reviewed.
* Reviewing a pull request in CI requires GitHub authentication: `GITHUB_TOKEN` or `GH_TOKEN` in the environment, or an authenticated `gh` session. Local runs without credentials fall back to anonymous access to public repositories.
* The default lenses come from the `standard` profile and are pinned to a specific version of the `tessl/code-review` plugin, so the default review does not change when the plugin publishes a new version.
* Selected lenses contribute to one review of the whole change.
* Transcript capture and upload require the internal `TESSL_CODE_REVIEW_USAGE_DIAGNOSTICS=1` gate during the initial release. A gated CI or Cloud Launch run captures without project configuration; a gated developer run also requires agent-log collection with the `tessl-cli` provider enabled. The general usage-sharing preference does not control this diagnostic-only capture.
* By default the command runs a review and prints the result, publishing nothing. Pass `--publish` to post the completed review to the pull request it reviewed as one native GitHub review: a summary body, an inline comment on each finding GitHub can anchor to a changed line, and a reply on each earlier finding's thread this round reconciled.
* Inline placement is attempted, not guaranteed. A finding GitHub cannot anchor to a changed line is carried in the summary body instead. If GitHub rejects the whole batch because it cannot resolve an anchor, the CLI retries once with every finding in the summary instead, and that retry can itself fail or find that the head has moved on. Replies to earlier threads are best effort in the same way: a failure to read or post them warns and leaves the published review standing.
* `--publish` takes a value rather than being a boolean, because the two ways to publish differ in what they claim. `comment` states no position on the change. `verdict` carries the review's own conclusion, and the CLI resolves it into an approval or a request for changes once the review has run, since the verdict does not exist before then. There is no way to ask for an approval that contradicts what the review found. Some rejections of a review carrying that event lead the CLI to retry once as a plain comment, and the receipt records that downgrade; others end the run without publishing. Repository policy and token permissions are the usual reasons, but the receipt does not establish the cause, and the retry can fail as well.
* Publishing applies to pull requests only, needs a token that can write pull requests, and is refused for a replayed fixture.
* With `--json`, a `publication` receipt appears once the run reaches a terminal publication state, and is absent otherwise, including when the review itself failed and when publication failed. Its `status` is `published`, `published-with-policy-fallback` (the verdict was downgraded to a comment), `superseded` (the pull request head moved while the review ran, so nothing was published), or `reused` (this attempt had already published its review). A consumer that depends on the review event should branch on `status` first: `publishedEvent` is carried by `published` and `published-with-policy-fallback` only, and it says what was submitted rather than what was requested.
* The [Tessl Review GitHub App](/tutorials/setting-up-agentic-code-review.md) is the supported way to run reviews on pull requests automatically.

#### YAML file profiles

Pass a profile path explicitly. Tessl does not discover profile files automatically:

```sh
$ tessl code review --profile ./.tessl-code-review.yml
```

The file must be a block-style YAML mapping with `schemaVersion: 1` and a non-empty, ordered `lenses` list:

```yaml
schemaVersion: 1
reviewMode: standard
requestChangesAt: major
ignore:
  - '**/*.generated.ts'
  - vendor/**
  - '**/__snapshots__/**'
lenses:
  - ref: ./review-lenses/backend/SKILL.md
    globs:
      - apps/backend/**
      - '!apps/backend/**/*.generated.ts'
  - ref: tessl/code-review@0.2.0#review-security-and-privacy
    globs:
      - infra/**
  - ref: ./review-lenses/general/SKILL.md
```

Each `ref` is a local `SKILL.md` path or skill directory, an installed skill name, or a registry reference. Local paths are resolved relative to the profile and must remain inside the repository. A lens without `globs` applies to the whole change.

Globs are case-sensitive, repository-relative POSIX patterns. Each list must contain at least one positive pattern. Patterns are evaluated in order: a matching positive pattern includes a path, a matching pattern prefixed with `!` excludes it, and a later positive pattern can include it again. For a renamed file, the lens is selected when either the old or new path matches.

The top-level `ignore` list bounds which paths any lens reviews, so you exclude generated code, lockfiles, snapshots, or vendored directories once instead of repeating a `!` negation in every lens. Each pattern is a repository-relative POSIX glob, and each is positive: it excludes what it matches, so a leading `!` is rejected rather than read as a double negative. The list applies to every lens, including a lens that declares no `globs` of its own; a lens's own `globs` still narrow it further, and `ignore` overrides anything a lens selected. At most 64 patterns are allowed, and a bare `**` (which would exclude everything) is rejected. Because a file is selected when either rename endpoint matches, a file renamed into an ignored path is still reviewed, and that ignored path appears in the rename patch. `ignore` bounds which paths a lens reviews; it is not a way to keep paths or their contents out of a model's context.

Each lens receives only its selected files in its prompt and the `diff_stat`, `diff_files`, `diff_file`, and `diff_full` tools. Lenses with no matching files do not run or count toward the limit of eight lenses. If no lens matches, the command exits successfully with a skipped result and does not imply approval.

Passing `--skill` replaces the file profile's complete lens list and its routing.

The file may set `effort` for every lens, and any lens may set its own `effort` to think harder or less hard than the rest. A lens without one runs at the file's `effort`; with neither, the model applies its own default. `--effort` applies to every lens and takes precedence over both.

`reviewMode` controls the blocking strength required from an eligible finding. `strict` blocks at zero, `standard` at one, and `relaxed` at two. Omit it to use `standard`. Low-confidence fresh findings are omitted in every mode. Pre-existing findings never block.

Each valid finding is assessed internally by consequence severity, likelihood, confidence, and relationship to the change. The CLI combines consequence and likelihood into the stable published severity: Critical consequence becomes Critical, Major, or Minor at High, Medium, or Low likelihood; Major consequence becomes Major, Major, or Minor; Minor consequence becomes Minor, Minor, or Nit; and Nit remains Nit. Confidence remains supporting assessment data rather than changing severity or blocking strength.

`requestChangesAt` sets the minimum consequence severity eligible to block: `critical`, `major`, `minor`, or `nit`, defaulting to `major`. Each consequence level above that baseline adds one strength point; Low, Medium, and High likelihood add zero, one, and two. A finding blocks when its strength reaches the selected review mode's threshold.

Because published severity also reflects likelihood, a Strict or Standard review can require a change for a finding displayed below `requestChangesAt`. The finding's `requiresChanges` value is authoritative.

The first review and an authorised full re-review show every valid optional finding. An incremental re-review shows a fresh finding only when it blocks and continues to reconcile earlier findings.

Whether a changes-requested result blocks a merge depends on how the review runs, and in every case a merge is held only by the repository's branch protection or ruleset. Under the [Tessl Review GitHub App](/tutorials/setting-up-agentic-code-review.md), the repository's review behavior (Enforcing by default, or Advisory) sets whether the `Tessl Reviewer` check passes or fails on a changes-requested result; that check holds a merge only when branch protection requires it. Under the unsupported [GitHub Action](/tutorials/setting-up-agentic-code-review/code-review-action.md), the Action's `mode` input decides whether its check fails, and again branch protection decides whether a failing check holds the pull request.

File profiles also work with the GitHub Action. Set its `profile` input to the repository-relative path.

**Examples**

```sh
# Review the current change (the current PR in CI, otherwise the local change)
tessl code review

# Review a specific pull request
tessl code review --pr 128

# Review an explicit Git range
tessl code review --base origin/main --head my-branch

# Review with specific lenses (replaces the default set; pin the version)
tessl code review --skill tessl/code-review@0.2.0#review-security-and-privacy --skill tessl/code-review@0.2.0#review-correctness-and-data-integrity

# Route a local review with a repository-owned YAML profile
$ tessl code review --profile ./.tessl-code-review.yml

# Review a pull request and publish the verdict to it
$ tessl code review --pr 128 --publish verdict

# Let a bot login ask the review to approve instead of reviewing
tessl code review --pr 128 --approver my-agent[bot]

# Output as JSON
tessl code review --json
```

***

## Launch

The `tessl launch` family runs agent workflows. Use `tessl launch skill` to run a specific skill with a chosen agent, or `tessl launch <agent>` to open an interactive agent session. The `list`, `view`, and `logs` subcommands inspect past cloud launch runs.

### tessl launch \<agent>

Launch a coding agent in an interactive session.

**Usage**

```sh
tessl launch <agent>
```

**Arguments**

* `agent` (string, required): Coding agent to launch. Supported values: `claude-code`, `codex`, `gemini`, `antigravity`, `cursor`, `copilot`, `openhands`, `tessl-agent`.

**Examples**

```sh
# Launch Claude Code
tessl launch claude-code

# Launch Cursor
tessl launch cursor
```

### tessl launch skill

Run a skill using an agent.

**Usage**

```sh
tessl launch skill <skill> [--agent <agent>] [--interactive] [--yolo] [--instructions <text>]
tessl launch skill <skill> --cloud --repo <owner/name> [--agent <agent>] [cloud flags]
```

**Arguments**

* `skill` (string, required): The skill to run. The local and cloud modes accept different argument forms.

  **Local (without `--cloud`)**

  * Installed skill name: a bare name with no slashes (e.g., `canary-reporter`), resolved from skills installed in the current project.
  * `file:path`: resolved on your machine. Without a `#skill` selector, the directory must contain a top-level `SKILL.md`. With a `#skill` selector (e.g., `file:./my-plugin#review-diff`), it looks for `skills/<name>/SKILL.md` inside the directory.

  Any value containing a `/` is treated as a filesystem path, not a registry ref. Registry-style values (e.g., `workspace/plugin`) do not resolve remotely in local mode; they are looked up as relative paths on disk.

  **Cloud (with `--cloud`)**

  * Registry ref: `workspace/plugin[@version]`, or a bare `plugin[@version]` resolved across the workspaces you can see.
  * `file:path/to/plugin`: a path inside the cloned target repository (not the caller's machine), pointing at the plugin root (the directory holding `.tessl-plugin/plugin.json` or `tile.json`).

  Either cloud form may carry a trailing `#skill` selector (for example `workspace/plugin@1.0.0#review-diff` or `file:tiles/my-plugin#review-diff`). It installs the whole plugin and runs the named skill. The selector is required when the plugin exposes more than one skill.

**Flags**

* `--agent` (string, optional): Agent to run the skill with. Supported values: `claude-code`, `codex`, `gemini`, `antigravity`, `cursor`, `copilot`, `openhands`, `tessl-agent`. Required for local (non-cloud) runs; with `--cloud` it selects the cloud strategy (supported: `claude-code`, `cursor`, `codex`, `tessl-agent`).
* `--interactive` / `-i` (boolean, optional): Run the agent in the foreground instead of streaming output.
* `--yolo` (boolean, optional): Skip agent permission prompts and approval checks.
* `--instructions` (string, optional): Instructions to append to the skill prompt.

**Notes**

* In cloud mode, a `file:` path must point at the plugin root inside the target repository. Pointing it at a skill subdirectory fails at the install step because that subdirectory has no `.tessl-plugin/plugin.json` or `tile.json`. Use the plugin root with a `#skill` selector instead.
* In local mode, the `#skill` selector looks for `skills/<name>/SKILL.md` relative to the given directory. It applies when the directory is a multi-skill plugin root. It does not apply to a single-skill directory (which uses a top-level `SKILL.md`) or a bare installed skill name.
* Local mode does not resolve registry-style refs (e.g., `workspace/plugin`). Any value with a `/` is treated as a filesystem path.

**Cloud flags**

Run the skill against a repository in the cloud rather than locally.

* `--cloud` (boolean, optional): Run the skill against a repo in the cloud.
* `--repo` (string, optional): Target repository as `owner/name` or URL (required with `--cloud`).
* `--base-branch` (string, optional): Branch to clone and target the PR against (default: `main`).
* `--snapshot` (string, optional): Recipe-runner snapshot to run the cloud launch on.
* `--env-file` (string, optional): Path to a `.env` file whose variables are encrypted and made available to the cloud launch.
* `--workspace` (string, optional): Name of workspace to launch in (default: linked project workspace).
* `--wait` / `--no-wait` (boolean, optional): Wait for the cloud launch to finish before returning (default: wait; use `--no-wait` to return immediately).
* `--label` (string, optional): Label to describe this launch run.
* `--model` (string, optional): Model to use for the cloud launch run.
* `--cwd` (string, optional): Subdirectory to run the skill in, relative to the current directory (default: repo root).

**Examples**

```sh
# Run an installed skill locally by name
tessl launch skill canary-reporter --agent tessl-agent

# Run a skill from a single-skill directory (contains a top-level SKILL.md)
tessl launch skill file:./my-skill --agent claude-code

# Run one skill from a multi-skill plugin directory
tessl launch skill file:./my-plugin#review-diff --agent tessl-agent

# Run a skill interactively with Claude Code
tessl launch skill file:./my-plugin#review-diff --agent claude-code --interactive

# Skip permission prompts
tessl launch skill file:./my-plugin#review-diff --agent tessl-agent --yolo

# Run with additional instructions
tessl launch skill file:./my-plugin#review-diff --agent tessl-agent --instructions "Focus on the auth module only"

# Run a registry plugin in the cloud and wait for the result
tessl launch skill engteam/my-plugin --cloud --repo tesslio/monorepo --agent tessl-agent

# Choose one skill from a multi-skill registry plugin in the cloud
tessl launch skill engteam/my-plugin#review-diff --cloud --repo tesslio/monorepo --agent tessl-agent

# Run a local plugin path against a cloud repo
tessl launch skill file:tiles/my-plugin#review-diff --cloud --repo tesslio/monorepo --agent tessl-agent

# Trigger a cloud launch without waiting for completion
tessl launch skill engteam/my-plugin --cloud --repo tesslio/monorepo --no-wait
```

### tessl launch list

List recent launch runs in reverse chronological order.

**Usage**

```sh
tessl launch list [--workspace <name>] [--limit <count>] [--json]
```

**Flags**

* `--workspace` / `-w` (string, optional): Filter by workspace name.
* `--limit` (number, optional): Maximum number of launch runs to display (default: 20).
* `--json` (boolean, optional): Output as JSON.

**Examples**

```sh
# List recent launch runs
tessl launch list

# List runs for a specific workspace
tessl launch list --workspace engteam

# List as JSON
tessl launch list --json
```

### tessl launch resume

Resume a completed cloud launch run with its saved workspace archive. A run stays resumable for 7 days after that archive is saved. After that the archive is deleted, so start a new launch run instead.

**Usage**

```sh
tessl launch resume <id> [--instructions <text>] [--label <label>] [--json]
```

**Arguments**

* `id` (string, required): Parent launch run ID to resume.

**Flags**

* `--instructions` / `-i` (string, optional): Follow-up instructions for the resumed run. Overrides the parent's instructions.
* `--label` (string, optional): Label for the resumed run.
* `--json` (boolean, optional): Output as JSON.

**Examples**

```sh
# Resume a recent run with follow-up instructions
tessl launch resume 019c4791-9eec-7458-b28a-6c94405a3d38 --instructions "Address the review comments"
```

### tessl launch view

View status and details for a launch run.

**Usage**

```sh
tessl launch view [--json] <id>
```

**Arguments**

* `id` (string, required): Launch run ID.

**Flags**

* `--json` (boolean, optional): Output as JSON.

**Examples**

```sh
# View a specific launch run
tessl launch view 019c4791-9eec-7458-b28a-6c94405a3d38
```

### tessl launch logs

Print agent logs for a launch run.

**Usage**

```sh
tessl launch logs <launchRunId>
```

**Arguments**

* `launchRunId` (string, required): Launch run ID.

**Examples**

```sh
# Print logs for a launch run
tessl launch logs 019c4791-9eec-7458-b28a-6c94405a3d38
```

***

## Schedules

The `tessl schedule` family runs a plugin against a repository on a cron. The plugin owns the task; the schedule owns the timing. Each time a schedule fires, Tessl starts a cloud launch run and records the result. Inspect schedules with `list`, `view`, and `runs`, and manage them with `pause`, `resume`, `update`, `trigger`, and `delete`.

For the concepts and a walkthrough, see [Schedules](/automations/overview/overview.md). For the secrets a run executes with, see [Environments](/automations/environments.md).

{% hint style="info" %}
Tessl skips a tick if the previous run from the same schedule is still active when the next one would start. There is no queue, so a skipped tick does not run later.
{% endhint %}

### tessl schedule list

List scheduled runs.

**Usage**

```sh
tessl schedule list [--workspace <name>] [--status <status>] [--limit <count>] [--json]
```

**Flags**

* `--workspace` / `-w` (string, optional): Filter by workspace name.
* `--status` (string, optional): Filter by status. Supported values: `active`, `paused`.
* `--limit` (number, optional): Maximum number of scheduled runs to display (default: 20).
* `--json` (boolean, optional): Output as JSON.

**Examples**

```sh
# List scheduled runs
tessl schedule list

# List only paused schedules
tessl schedule list --status paused

# List schedules in a specific workspace
tessl schedule list --workspace engteam

# List as JSON
tessl schedule list --json
```

### tessl schedule view

View config, cron, and next/last run for a scheduled run.

**Usage**

```sh
tessl schedule view [--json] <id>
```

**Arguments**

* `id` (string, required): Scheduled run ID.

**Flags**

* `--json` (boolean, optional): Output as JSON.

**Examples**

```sh
# View a schedule
tessl schedule view 019c4791-9eec-7458-b28a-6c94405a3d38
```

### tessl schedule runs

List the launch runs a scheduled run has spawned.

**Usage**

```sh
tessl schedule runs [--limit <count>] [--json] <id>
```

**Arguments**

* `id` (string, required): Scheduled run ID.

**Flags**

* `--limit` (number, optional): Maximum number of launch runs to display (default: 20).
* `--json` (boolean, optional): Output as JSON.

**Examples**

```sh
# List the runs a schedule has spawned
tessl schedule runs 019c4791-9eec-7458-b28a-6c94405a3d38

# Show the last 5 runs as JSON
tessl schedule runs 019c4791-9eec-7458-b28a-6c94405a3d38 --limit 5 --json
```

### tessl schedule pause

Pause a scheduled run.

**Usage**

```sh
tessl schedule pause [--json] <id>
```

**Arguments**

* `id` (string, required): Scheduled run ID.

**Flags**

* `--json` (boolean, optional): Output as JSON.

**Examples**

```sh
# Pause a schedule
tessl schedule pause 019c4791-9eec-7458-b28a-6c94405a3d38
```

### tessl schedule resume

Resume a paused scheduled run.

**Usage**

```sh
tessl schedule resume [--json] <id>
```

**Arguments**

* `id` (string, required): Scheduled run ID.

**Flags**

* `--json` (boolean, optional): Output as JSON.

**Examples**

```sh
# Resume a paused schedule
tessl schedule resume 019c4791-9eec-7458-b28a-6c94405a3d38
```

### tessl schedule update

Update a scheduled run's cron, timezone, or label.

**Usage**

```sh
tessl schedule update [--cron <expr>] [--timezone <name>] [--label <text>] [--json] <id>
```

**Arguments**

* `id` (string, required): Scheduled run ID.

**Flags**

* `--cron` (string, optional): New cron expression, interpreted in the schedule timezone unless `--timezone` is also provided.
* `--timezone` (string, optional): New IANA timezone the cron is interpreted in.
* `--label` (string, optional): New label to describe this schedule.
* `--json` (boolean, optional): Output as JSON.

**Notes**

* At least one of `--cron`, `--timezone`, or `--label` is required.
* Only the cron, timezone, and label can be changed. To change the skill, repo, environment, or any other launch config, delete the schedule and create a new one.

**Examples**

```sh
# Move a schedule to 07:00 daily
tessl schedule update 019c4791-9eec-7458-b28a-6c94405a3d38 --cron "0 7 * * *"

# Change the timezone
tessl schedule update 019c4791-9eec-7458-b28a-6c94405a3d38 --timezone America/New_York

# Rename a schedule
tessl schedule update 019c4791-9eec-7458-b28a-6c94405a3d38 --label "Nightly docs audit"
```

### tessl schedule trigger

Fire a scheduled run now, out of band.

**Usage**

```sh
tessl schedule trigger [--json] <id>
```

**Arguments**

* `id` (string, required): Scheduled run ID.

**Flags**

* `--json` (boolean, optional): Output as JSON.

**Notes**

* Triggering dispatches a launch run asynchronously and returns immediately. It does not change the cron and does not affect the next scheduled tick. Use `tessl schedule runs <id>` to see the spawned run and its result.

**Examples**

```sh
# Run a schedule now
tessl schedule trigger 019c4791-9eec-7458-b28a-6c94405a3d38
```

### tessl schedule delete

Delete a scheduled run.

**Usage**

```sh
tessl schedule delete <id>
```

**Arguments**

* `id` (string, required): Scheduled run ID.

**Notes**

* Deleting a schedule stops future runs. Launch runs it has already spawned are kept.

**Examples**

```sh
# Delete a schedule
tessl schedule delete 019c4791-9eec-7458-b28a-6c94405a3d38
```


---

# 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/reference/cli-commands.md?ask=<question>&goal=<endgoal>
```

`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.