CLI commands

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

Getting started

tessl help

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

tessl login

Authenticate with Tessl.

Usage

tessl login

Alternative

tessl auth login

tessl logout

Sign out and clear credentials.

Usage

tessl logout

Alternative

tessl auth logout

tessl whoami

Show current authenticated user.

Usage

tessl whoami

Alternative

tessl auth whoami

tessl auth token

Generate a new Tessl API key.

Usage

tessl auth token [--expiry-date <date>]

Flags

• --expiry-date (string, optional): Expiration date for the API key in YYYY-MM-DD format (e.g., 2025-10-05)

Examples

# Generate an API key with default expiration
tessl auth token

# Generate an API key that expires on a specific date
tessl auth token --expiry-date 2025-12-31

---

Setup and initialization

tessl init

Set up your project and sync dependencies.

Usage

tessl init [--project-dependencies <option>] [--agent <name>]...

Flags

• --project-dependencies (string, optional): Configure project dependencies mode. Options: install (default), skip, ask

• --agent (string, optional, repeatable): Configure MCP for coding agent. Supported values: claude-code, cursor, gemini, codex, copilot, copilot-vscode, agents. Can specify multiple agents. See Custom Agents for information on configuring additional agents.

Notes

• Configures MCP server settings for AI coding agents

• Automatically syncs project dependencies when configured

• Important: Open source dependencies must be installed in your project (via npm install, pip install, etc.) before running tessl init so that Tessl can detect them and install the relevant tiles

Examples

# 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

# Initialize but skip automatic dependency sync
tessl init --project-dependencies skip

---

Project dependencies

tessl install

Install tiles into your project. Tiles 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

tessl install [--project-dependencies] [--global] [--skill <value>]... [--yes] [--verbose] [--watch-local] [--dangerously-ignore-security] <source>...

Arguments

• source (string, required): Tile or GitHub URL to install. Can be:

  • Registry tile: workspace/tile[@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

• --project-dependencies (boolean, optional): Scan project dependencies and install matching tiles (interactive). Dependencies should be installed locally via package manager prior to using this. When used in a monorepo, scans dependencies from the current working directory.

• --global / -g (boolean, optional): Install tiles globally to ~/.tessl/ instead of the current project. Global tiles are available across all your projects.

• --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 tiles and reinstall on changes

• --dangerously-ignore-security (boolean, optional): Bypass security gate for high/critical findings

Notes

• Tiles are installed to .tessl/tiles/<workspace>/<tile>/ in your project (or ~/.tessl/tiles/ when using --global)

• Your project's tessl.json is automatically updated with the tile reference

• If a tile 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 (tile.json expected in the path)

• Monorepo support: When using --project-dependencies in a monorepo, the command scans dependencies from your current working directory. This allows you to initialize Tessl at the monorepo root and then install project-specific dependencies from subfolders.

• Security gating: If a tile has 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 --dangerously-ignore-security to skip this prompt automatically.

Examples

# Install a specific tile from registry
tessl install tessl/[email protected]

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

# Install tiles for all project dependencies
tessl install --project-dependencies

# Install all project dependencies without prompts
tessl install --project-dependencies --yes

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

# 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

# Monorepo workflow: Initialize at root, then install dependencies from subfolder
tessl init
cd backend
tessl install --project-dependencies

# Install a tile globally (available across all projects)
tessl install --global tessl/svelte

tessl search

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

Usage

tessl search [--type skills|docs|rules] [<query>]

Flags

• --type (string, optional): Filter by content type. Supported values: skills, docs, rules

Arguments

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

Examples

# Search for tiles matching "svelte"
tessl search svelte

# Interactive search
tessl search

tessl uninstall

Uninstall tiles from your project.

Usage

tessl uninstall [--global] <workspace/tile>

Arguments

• workspace/tile (string, required): Full tile name in the format workspace/tile

Flags

• --global / -g (boolean, optional): Uninstall tiles from the global ~/.tessl/ directory instead of the current project

Notes

• Removes the tile from tessl.json and deletes files from .tessl/tiles/

• Does not require authentication (local operation only)

Examples

# Uninstall a tile from the current project
tessl uninstall tessl/svelte

# Uninstall a globally installed tile
tessl uninstall --global tessl/svelte

tessl list

List all installed tiles in your project.

Usage

tessl list [--json]

Flags

• --json / --no-json (boolean, optional): Output tiles as JSON instead of human-readable format

Notes

• Lists all tiles installed in your project based on tessl.json

• Shows tile names in the format workspace/tile with their versions

• Does not require authentication (local operation only)

Examples

# List all installed tiles
tessl list

# List tiles in JSON format
tessl list --json

tessl outdated

Check for available tile updates.

Usage

tessl outdated [--json]

Flags

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

Examples

# Check for outdated tiles
tessl outdated

# Output as JSON
tessl outdated --json

tessl update

Update tiles to newer versions.

Usage

tessl update [--yes] [--force] [--dangerously-ignore-security] [<tile>]

Flags

• --yes / -y (boolean, optional): Skip prompts and update all compatible tiles

• --force / -f (boolean, optional): Include breaking updates

• --dangerously-ignore-security (boolean, optional): Bypass security gate for high/critical findings

Arguments

• tile (string, optional): Tile to update in the format workspace/tile. If omitted, updates all tiles.

Notes

• If a tile has critical or high Snyk security findings in the new version, you will be asked for permission before the update is applied. Use --dangerously-ignore-security to skip this prompt automatically.

Examples

# Update all tiles interactively
tessl update

# Update all tiles without prompts
tessl update --yes

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

# Include breaking updates
tessl update --force

---

Skill management

tessl skill new

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

Usage

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

Flags

• --name (string, optional): Name of the skill

• --description (string, optional): When the skill should be triggered

• --workspace (string, optional): Workspace to create the skill in

• --path (string, optional): Local path where the skill directory will be created

• --install (boolean, optional): Install the skill locally after creation

• --public (boolean, optional): Make the skill public (default is 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

# 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 tile.json from SKILL.md.

Usage

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

Flags

• --workspace (string, optional): Workspace for the skill

• --public (boolean, optional): Make skill public (default: prompt)

• --force (boolean, optional): Overwrite existing tile.json without prompting

Arguments

• path (string, optional): Path to directory containing SKILL.md or to SKILL.md file. Defaults to current directory if omitted.

Examples

# Import from current directory
tessl skill import

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

# Import from GitHub
tessl skill import https://github.com/user/my-skill

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

tessl skill lint

Validate skill structure and contents.

Usage

tessl skill lint [<path/to/tile.json>]

Arguments

• path/to/tile.json (string, optional): Path to skill folder or tile.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

# Lint skill in current directory
tessl skill lint

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

# Lint skill using tile.json path
tessl skill lint ./my-skill/tile.json

tessl skill publish

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

Usage

tessl skill publish [--workspace WORKSPACE] [--public] [--force] [--bump patch|minor|major] [--dry-run] [--skip-evals] [<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 tile.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

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 Evaluating skills)

Examples

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

Review a skill file for quality and compliance.

Usage

tessl skill review [--json] [--optimize] [--max-iterations <count>] [--skill <name>] [--yes] [<path-or-url>]

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

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

• If optimize flag used automatically loops through rounds of skill review and changes to improve your skill in place

Examples

Reviewing a skill

# Review skill in current directory
tessl skill review

# Review skill at specific path
tessl skill review ./my-skill

# Review specific skill by name from a tile with multiple skills
tessl skill review --skill pdf ./my-tile

Optimizing a skill

# Optimize skill in current directory
tessl skill review --optimize

# Optimize skill at specific path with 10 rounds of iteration
tessl skill review --optimize --max-iterations 10 ./my-skill

# Optimize skill by name from a tile with multiple skills
tessl skill review --optimize --skill pdf ./my-tile

# Optimize and auto-apply changes without confirmation prompt
tessl skill review --optimize --yes ./my-skill

---

Tile management

tessl tile new

Create a new tile with an interactive wizard.

Usage

tessl tile new [--name <workspace/tile-name>] [--summary <description>] [--path <path>] [--docs] [--rules <rule-name>]... [--workspace <workspace>] [--skill] [--skill-name <name>] [--skill-description <description>] [--describes <purl>] [--install] [--public]

Flags

• --name (string, optional): Tile name in format workspace/tile-name

• --summary (string, optional): Brief description of the tile

• --path (string, optional): Directory path where tile will be created

• --docs / --no-docs (boolean, optional): Include documentation

• --rules (string, repeatable, optional): Include rule by name (can be specified multiple times)

• --workspace (string, optional): Workspace for the tile

• --skill / --no-skill (boolean, optional): Include a skill in the tile

• --skill-name (string, optional): Skill name (implies --skill)

• --skill-description (string, optional): Skill description (required with --skill or --skill-name)

• --describes (string, optional): PURL of package this tile documents

• --install / --no-install (boolean, optional): Automatically install in current project

• --public / --no-public (boolean, optional): Make tile public (default: private)

Notes

• Creates a new tile directory with a basic tile.json template

• If run without flags, launches an interactive wizard to guide you through tile creation

• Use --skill or --skill-name to create a tile with a skill component

Examples

# Interactive wizard mode
tessl tile new

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

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

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

tessl tile lint

Validate tile structure and contents

Usage

tessl tile lint [<source>]

Arguments

• source (string, optional): Path to the tile directory to lint. Defaults to current directory if omitted.

tessl tile pack

Package a tile into a .tgz file.

Usage

tessl tile pack [--output path] [<source>]

Flags

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

Arguments

• source (string, optional): Path to tile folder or tile.json. Defaults to current directory if omitted.

tessl tile info

Show tile details from the registry.

Usage

tessl tile info [<name-or-path>]

Arguments

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

Examples

# Show info for tile in current directory
tessl tile info

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

# Show info for a specific version
tessl tile info engteam/[email protected]

tessl tile publish

Publish tiles to the Tessl registry. This command bundles skills, rules, documentation into a tile.

Usage

tessl tile publish [--dry-run] [--bump patch|minor|major] [--skip-evals] [<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

Arguments

• path (string, optional): Path to the tile directory to publish. Defaults to current directory if omitted.

Examples

# Publish a tile from current directory
tessl tile publish

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

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

tessl tile unpublish

Unpublish tiles from the registry.

Usage

tessl tile unpublish --tile <tile-name>

Flags

• --tile (string, required): Tile to unpublish in the format workspace/tile@version

Notes

• Only available within 2 days of publishing

Examples

# Unpublish a specific tile version
tessl tile unpublish --tile myworkspace/[email protected]

tessl tile archive

Archive tiles in the registry.

Usage

tessl tile archive --tile <tile-name> --reason <reason>

Flags

• --tile (string, required): Tile to archive in the format workspace/tile@version

• --reason (string, required): Reason for archiving the tile

Notes

• Prevents new installations while preserving existing installations

Examples

# Archive a tile with a reason
tessl tile archive --tile myworkspace/[email protected] --reason "Deprecated in favor of v2"

---

Workspace management

Workspaces enable you to create private collections of tiles 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

tessl workspace create [name]

Arguments

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

Examples

# Create a workspace
tessl workspace create myworkspace

# Interactive creation
tessl workspace create

tessl workspace list

List all workspaces that you are a member of.

Usage

tessl workspace list

tessl workspace delete

Delete an existing workspace.

Usage

tessl workspace delete [name]

Arguments

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

Examples

# Delete a workspace
tessl workspace delete myworkspace

# Interactive deletion
tessl workspace delete

tessl workspace add-member

Add a user to a workspace with specified permissions.

Usage

tessl workspace add-member [--workspace <name>] [--user <user>] [--role <role>]

Flags

• --workspace (string, optional): The name or ID of the workspace

• --user (string, optional): The username or ID of the user to add

• --role (string, optional): The role of the user. Options:

  • member publisher

  • manager owner

See Roles for more information

Examples

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

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

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

tessl workspace remove-member

Remove a user from a workspace.

Usage

tessl workspace remove-member [--workspace <name>] [--user <user>]

Flags

• --workspace (string, optional): The name or ID of the workspace

• --user (string, optional): The username or ID of the user to remove

Examples

# Remove a member
tessl workspace remove-member --workspace myworkspace --user [email protected]

# Interactive mode
tessl workspace remove-member

tessl workspace list-members

List all members of a workspace.

Usage

tessl workspace list-members [name]

Arguments

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

Examples

# 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

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

# 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

tessl workspace unarchive <name>

Arguments

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

Examples

# Unarchive a workspace
tessl workspace unarchive myworkspace

---

Configuration management

tessl config get

Get a configuration value or show all configuration.

Usage

tessl config get [<key>]

Arguments

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

Examples

# Show all configuration
tessl config get

# Get a specific configuration value
tessl config get analytics.enabled

tessl config set

Set a configuration value.

Usage

tessl config set <key> <value>

Arguments

• key (string, required): Configuration key to set

• value (string, required): Value to set

Examples

# Set a configuration value
tessl config set analytics.enabled false

tessl config list

List all configuration values.

Usage

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

# List all configuration
tessl config list

# List a specific configuration key
tessl config list analytics.enabled

tessl config add

Add one or more values to a configuration array.

Usage

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

# 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

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

# 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

tessl doctor [--json]

Flags

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

Examples

# Run diagnostics with human-readable output
tessl doctor

# Output diagnostics as JSON
tessl doctor --json

tessl feedback

Send feedback to the Tessl team.

Usage

tessl feedback [<message>]

Arguments

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

Examples

# 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

tessl cli update [--target <version>] [--dry-run]

Note: --target can be shortened to -t

Flags

• --target or -t (string, optional): Target version to update to (e.g., v1.0.0)

• --dry-run (boolean, optional): Show what would be run without executing the update

Examples

# Update to the latest version
tessl cli update

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

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

---

Model Context Protocol (MCP)

tessl mcp start

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

Usage

tessl mcp start

---

Repository

tessl repo select-commits

Browse recent commits in a repository and select which ones to evaluate. Used as the first step in setting up a codebase eval.

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

Usage

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

# 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

---

Scenario management

Scenario management and codebase 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 Evaluate your codebase.

tessl scenario generate

Generate eval scenarios from a tile 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

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

Arguments

• source (string, required): Tile 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 (tile 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.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

# 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 tile
$ tessl scenario generate ./my-tile --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

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

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

# 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

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

# 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 Evaluate your codebase and Evaluate skill quality using scenarios.

tessl eval run

Run evaluations for a tile or a codebase scenarios directory. The CLI auto-detects the eval type from the source:

• Codebase eval — source directory contains scenario.json fixtures → runs with smart defaults (agent claude:claude-sonnet-4-6, context pattern from fixture.exclude, context ref infer)

• Tile eval — source contains tile.json → runs the tile's own evals

Usage

tessl eval run [--workspace <name>] [--agent <agent:model>]... [--context-pattern "<globs>"] [--context-ref <infer|HEAD|SHA>] [--runs <count>] [--variant <name>]... [--label <text>] [--force] [--json] [<source>]

Flags

• --force / -f (boolean, optional): Re-run all evals, including previously solved cases

• --workspace / -w (string, optional): Workspace name or ID

• --agent (string, optional, repeatable): Agent and model as agent:model (e.g. claude:claude-sonnet-4-6). Repeatable — each --agent creates a separate eval run. Default: claude:claude-sonnet-4-6

• --context-pattern (string, optional): Glob patterns for context files to inject for the with-context variant (codebase evals only). Defaults to fixture.exclude from scenario.json. Example: "**/*.knowledge.mdc"

• --context-ref (string, optional): Where to source context files from (codebase evals only). Values: infer (default — same commit as fixture.ref), HEAD (latest commit on default branch), or a specific SHA. Requires --context-pattern to be active.

• --runs / -n (number, optional): Number of times to repeat each agent configuration

• --variant (string, optional, repeatable): Restrict which variants to run. Supported values: without-context (baseline only) and with-context. Repeatable — pass both to run both. Defaults to running all variants. Codebase evals only.

• --label / -l (string, optional): A short description to attach to this eval run. Visible in tessl eval list and the Tessl web UI.

• --json (boolean, optional): Output eval run IDs as JSON immediately without polling

Arguments

• source (string, optional): Path to tile folder, tile.json, or scenarios directory. Defaults to current directory if omitted.

Notes

• For codebase evals, each scenario is solved twice by default when fixture.exclude is present: once without context files (baseline) and once with them injected (with-context). fixture.exclude is required — omitting it will result in an error. Use --variant to run only one variant (e.g. --variant without-context to run the baseline only).

• --context-pattern and --context-ref are only valid for codebase evals — passing them for a tile eval returns an error.

• Ctrl-C detaches without cancelling — runs continue server-side. The CLI prints each run ID.

Agent format: <agent>:<model> — supported agents: claude, cursor, codex

Examples

# Run codebase evals in current directory (auto-detects defaults)
$ tessl eval run ./evals/

# Run tile evals for a specific tile
$ tessl eval run ./my-tile

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

# Run with multiple agents
$ tessl eval run ./evals/ --agent=claude:claude-sonnet-4-6 --agent=cursor:auto

# Test updated context against historical scenarios
$ tessl eval run ./evals/ --context-ref=HEAD

# Override context pattern at run time
$ tessl eval run ./evals/ --context-pattern="**/*.knowledge.mdc"

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

# Run only the baseline variant (no context files injected)
$ tessl eval run ./evals/ --variant without-context

tessl eval compare

Compare agent scores across all runs for a local scenarios directory. The CLI fingerprints your local scenarios and fetches matching results from the server. Pass the same directory used with eval run.

Usage

tessl eval compare <path> [--workspace <name>] [--breakdown] [--json]

Arguments

• path (string, required): Path to the scenarios directory

Flags

• --workspace / -w (string, optional): Workspace name or ID. Required outside interactive mode.

• --breakdown (boolean, optional): Show per-scenario detail with all runs

• --json (boolean, optional): Output raw JSON

Notes

• Score colours: 🟢 ≥ 80% 🟡 ≥ 50% 🔴 < 50%

• When fixture.exclude is present in scenarios, output shows baseline vs with-context scores with a delta (Δ)

Examples

# Compare results for a batch
$ tessl eval compare ./evals/

# Show per-scenario breakdown
$ tessl eval compare ./evals/ --breakdown

tessl eval list

List recent eval runs in reverse chronological order.

Usage

tessl eval list [--json] [--limit <count>] [--mine] [--workspace <name>] [--tile <name>] [--status <status>] [--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 (string, optional): Filter by workspace name

• --tile (string, optional): Filter by tile name

• --status (string, optional): Filter by run status. Supported values: pending, in_progress, completed, failed

• --type (string, optional): Filter by eval type. Supported values: tile, skill, project

Notes

• The output table includes ID, Type, Subject, Status, Created By, and Created columns

• The Type column shows tile, project, or skill depending on the evaluation subject

• The Subject column formats entries by type: tiles as workspace/tile@version, projects as org/repo, and skills as org/repo:skillName

Examples

# List all recent eval runs
tessl eval list

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

# List only skill evaluations
tessl eval list --type skill

# 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

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

# 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

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

# 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 view-results

Show aggregated eval results across all scenarios and runs for a given repository. Unlike eval compare <path> which works from your local scenarios directory, this queries all results for the repo from the server.

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

Usage

tessl eval view-results <org/repo> [--workspace <name>] [--breakdown] [--json]

Arguments

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

Flags

• --workspace / -w (string, optional): Workspace name or ID. Required outside interactive mode.

• --breakdown (boolean, optional): Show per-scenario detail with all runs

• --json (boolean, optional): Output raw JSON