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.

On this page, repository means your Git repository. Tessl project means the stable home for Tessl in that repository.

Getting started

tessl help command

To see all available commands, run:

tessl --help

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

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

Authentication

Authenticate with Tessl.

Usage

tessl login

Alternative

tessl logout

Sign out and clear credentials.

Usage

Alternative

tessl whoami

Show current authenticated user.

Usage

Alternative

Setup and initialization

tessl init

Set up your repository and configure your coding agent.

Usage

Flags

--agent (string, optional, repeatable): Configure MCP for coding agent. Supported values: claude-code, cursor, gemini, codex, openhands, openclaw, copilot, copilot-vscode, agents, tessl-agent. Can specify multiple agents. See Custom Agents 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

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.

Usage

tessl project create

Create a new Tessl project for the current repository.

Usage

Flags

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

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

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

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

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, 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

tessl search

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

Usage

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
--json (boolean, optional): Output search results as JSON

Arguments

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

Examples

tessl uninstall

Uninstall plugins from your repository.

Usage

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

tessl list

List all installed plugins in your repository.

Usage

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

tessl outdated

Check for available plugin updates.

Usage

Flags

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

Examples

tessl update

Update plugins to newer versions.

Usage

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, 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

Skill management

tessl skill new

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

Usage

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

tessl skill import

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

Usage

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

tessl skill lint

Validate skill structure and contents.

Usage

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
Returns validation errors and warnings

Examples

tessl skill publish

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

Usage

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)

Examples

tessl skill review

Review a skill file for quality and compliance.

Usage

Flags

--json (boolean, optional): Output as JSON
--optimize (boolean, optional): Automatically improve the skill file and apply changes
--max-iterations (number, optional): Maximum number of improvement iterations (1-10, default: 3)
--skill (string, optional): Select specific skill to review from a remote repository
--yes / -y (boolean, optional): Skip confirmation prompt and auto-apply improvements
--threshold (number, optional): Minimum score percentage to pass (0-100, fails if below). 0 never fails (skips validation and score gating). Cannot be used with --optimize.

Arguments

path-or-url (string, optional): Path to SKILL.md, skill directory, or GitHub URL. Defaults to current directory if omitted.

Notes

Performs a comprehensive conformance review against the Agent Skills specification
Validates skill structure, formatting, and best practices
Provides detailed feedback on how to improve the skill
--optimize runs up to 3 improvement iterations by default, stopping early only if the skill reaches 100%
--threshold is for review-only mode (without --optimize) and causes the command to exit with a non-zero status if the score falls below the specified value
This command runs synchronously and requires you to be logged in (tessl login). For asynchronous, server-side reviews, including CI gating, custom rubrics, and the improve-and-review loop, use Tessl Review (tessl review run and tessl review fix)

Examples

Reviewing a skill

Optimizing a skill

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

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

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

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

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

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

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

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

tessl review list

List recent review runs.

Usage

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

tessl review retry

Re-run a failed review run.

Usage

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

tessl review fix

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

Usage

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)
--max-iterations (number, optional): Maximum improve→review iterations to attempt (1-10)
--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

Plugin management

tessl plugin new

Create a new plugin with an interactive wizard.

Usage

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

tessl plugin lint

Validate plugin structure and contents

Usage

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

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

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

Arguments

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

Examples

tessl plugin publish

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

Usage

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

Not sure what your published plugin's URL will look like? See Workspaces to learn how workspace and plugin names map to Registry URLs.

tessl plugin unpublish

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

Usage

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

tessl plugin archive

Archive plugins in the registry.

Usage

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

Organization management

tessl org list

List all organizations that you are a member of.

Usage

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.

tessl workspace create

Create a new workspace.

Usage

Flags

--org-id (string, optional): ID of organization to create the workspace in

Arguments

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

Examples

tessl workspace list

List all workspaces that you are a member of.

Usage

tessl workspace delete

Delete an existing workspace.

Usage

Arguments

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

Examples

tessl workspace add-member

Add a user to a workspace with specified permissions.

Usage

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 for more information

Examples

tessl workspace remove-member

Remove a user from a workspace.

Usage

Flags

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

Examples

tessl workspace list-members

List all members of a workspace.

Usage

Arguments

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

Examples

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

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

tessl workspace unarchive

Unarchive an archived workspace, making it active again.

Usage

Arguments

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

Examples

Configuration management

tessl config get

Get a configuration value or show all configuration.

Usage

Arguments

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

Examples

tessl config set

Set a configuration value.

Usage

Arguments

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

Examples

tessl config list

List all configuration values.

Usage

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

tessl config add

Add one or more values to a configuration array.

Usage

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

tessl config remove

Remove a value from a configuration array.

Usage

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

Diagnostics and utilities

tessl doctor

Run authentication and manifest diagnostics to troubleshoot issues.

Usage

Flags

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

Examples

tessl feedback

Send feedback to the Tessl team.

Usage

Arguments

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

Examples

CLI self-management

tessl cli update

Update the CLI to the latest or specified version.

Usage

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

API key management

tessl api-key create

Create an API key for a workspace.

Usage

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)

Examples

tessl api-key list

List API keys for a workspace.

Usage

Flags

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

Examples

tessl api-key delete

Delete an API key from a workspace.

Usage

Flags

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

Arguments

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

Examples

Model Context Protocol (MCP)

tessl mcp start

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

Usage

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 for how to register the upstream server and wire the proxy into an agent or plugin .mcp.json.

Usage

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.

Examples

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.

This command is not listed in tessl --help but works when invoked directly.

Usage

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

Inventory

tessl inventory import

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

Usage

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

Scenario management

Scenario management and evals are in public beta. Workflows and output formats may change in upcoming releases.

Scenario commands generate and manage eval scenarios from real repository commits. For a full walkthrough, see Prove a skill works using evaluation.

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

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

Examples

tessl scenario list

List recent scenario generation runs in reverse chronological order.

Alias: tessl scenarios list

Usage

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

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

tessl scenario download

Download generated scenarios to your local evals/ folder.

Alias: tessl scenarios download

Usage

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:

Examples

Evaluations

For more information on workflows and usage, see Prove a skill works using evaluation.

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

Flags

--agent (string, optional): Agent and model as agent:model (e.g. claude:claude-sonnet-4-6). Run tessl eval run --list-agents to see supported values. Default: claude:deepseek-v4-flash
--scorer-agent (string, optional): Override the agent and model used for the scoring step (agent:model); the solver agent is unchanged.
--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 immediately without polling.

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

Agent format: <agent>:<model> — run tessl eval run --list-agents for the supported list.

Examples

tessl eval list

List recent eval runs in reverse chronological order.

Usage

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