> 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

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`, `codex`, `openhands`, `openclaw`, `copilot`, `copilot-vscode`, `agents`. 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 [--new] [--workspace <name-or-id>] [<project-name>]
```

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

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

***

## 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] [--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)
* `--agent` (string, optional, repeatable): Override agents to install for. Supported values: `claude-code`, `cursor`, `gemini`, `codex`, `openhands`, `openclaw`, `copilot`, `copilot-vscode`, `agents`

**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] [--json] [<query>]
```

**Flags**

* `--global` / `-g` (boolean, optional): Install selected results 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**

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

# 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`, `codex`, `openhands`, `openclaw`, `copilot`, `copilot-vscode`, `agents`

**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 [<path/to/plugin>]
```

**Arguments**

* `path/to/plugin.json` (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] [<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

**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](/improving-your-skills/evaluating-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 review

Review a skill file for quality and compliance.

**Usage**

```sh
tessl skill review [--json] [--optimize] [--max-iterations <count>] [--skill <name>] [--yes] [--threshold <score>] [<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
* `--threshold` (number, optional): Minimum score percentage to pass (0-100, fails if below). 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 - useful as a CI gate

**Examples**

Reviewing a skill

```sh
# 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 plugin with multiple skills
tessl skill review --skill pdf ./my-plugin
```

Optimizing a skill

```bash
# 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 plugin with multiple skills
tessl skill review --optimize --skill pdf ./my-plugin

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

***

## 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
* 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 tile migrate

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

**Usage**

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

**Flags**

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

**Arguments**

* `path` (string, optional): Path to tile 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
```

***

## 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-id <uuid>] [<name>]
```

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

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

# Interactive creation
tessl workspace create

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

### tessl workspace list

List all workspaces that you are a member of.

**Usage**

```sh
tessl workspace list
```

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

### 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 analytics.enabled
```

### tessl config set

Set a configuration value.

**Usage**

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

**Arguments**

* `key` (string, required): Configuration key to set
* `value` (string, required): Value to set

**Examples**

```sh
# Set a configuration value
tessl config set analytics.enabled 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 analytics.enabled
```

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

**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>] [<api-key-id>]
```

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

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

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

***

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

***

## Repository

### tessl repo select-commits

Browse recent commits in a repository and select which ones to evaluate. Used as the first step in [evaluating your codebase](/improving-your-skills/evaluating-your-codebase.md).

{% 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
```

***

## 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 [Evaluate your codebase](/improving-your-skills/evaluating-your-codebase.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] <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

**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 [Evaluate your codebase](/improving-your-skills/evaluating-your-codebase.md) and [Evaluate skill quality using scenarios](/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).

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>] [--scorer-agent <agent: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] [<source>]
```

**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:claude-sonnet-4-6`
* `--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](/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.

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

**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
$ tessl eval run ./evals/ --agent claude: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>]
```

**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`, `in_progress`, `completed`, `failed`

**Notes**

* The output table includes ID, Type, Subject, Status, Created By, and Created columns
* The Type column shows `plugin`, `project`, or `skill` depending on the evaluation subject
* `project` means a run attached to a Tessl project
* The Subject column formats entries by type: plugins as `workspace/plugin@version`, projects as `org/repo`, and skills as `org/repo:skillName`

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


---

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

```
GET https://docs.tessl.io/reference/cli-commands.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.