Ctrlk
WebsitePress Kit
For the complete documentation index, see llms.txt. This page is also available as Markdown.

CLI commands

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

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

Getting started

tessl help command

To see all available commands, run:

tessl --help

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

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

Authentication

tessl login

Authenticate with Tessl.

Usage

$ tessl login [--device | --loopback]

Use --device to sign in with a device code instead of a local browser redirect. Use --loopback to sign in with a local browser redirect. Use only one of these flags.

Organizations using the EU region must have TESSL_ENV=app-eu set in the CLI's environment and use device login:

See Using the EU region for the full setup, including shell profiles, CI, and MCP servers.

Alternative

tessl logout

Sign out and clear credentials.

Usage

Alternative

tessl whoami

Show current authenticated user.

Usage

Alternative

Setup and initialization

tessl init

Set up your repository and configure your coding agent.

Usage

Flags

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

  • --name (string, optional): Project name for new tessl.json (default: current directory name)

Notes

  • Configures MCP server settings for AI coding agents

  • Creates a tessl.json manifest at the repository root

Examples

tessl project

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

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

Use these commands to create a new project, link this checkout to an existing project, or repair a missing or broken reference in tessl.json. For a workflow guide, see Manage projects from the CLI.

Usage

tessl project create

Create a new Tessl project for the current repository.

Usage

Flags

  • --nested (boolean, optional): Required when a parent directory has a tessl.json but the current directory has none. Creates a separate tessl.json and project for the current directory instead of reusing the parent project.

  • --new (boolean, optional): Create a new project for a different workspace. Use with --workspace and provide a project name when you intentionally want a separate new project for the same repository.

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

Arguments

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

Notes

  • Use this when this repository is not linked to a project yet and you want to create one in Tessl

  • This command always creates a new project

  • If this repository should use a project that already exists, use tessl project link instead

tessl project link

Link the current repository to an existing Tessl project.

Usage

Flags

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

Notes

  • Use this when the project already exists in Tessl and you want this repository to use it

  • This command only links to an existing project

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

tessl project repair

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

Usage

Flags

  • --json (boolean, optional): Output as JSON, for automation or agent workflows

  • --relink (boolean, optional): Relink this repository to a different existing project

  • --workspace (string, optional): Workspace name or ID for --relink

  • --project (string, optional): Project name for --relink target

  • --update-source (boolean, optional): Approve this repository as the linked project source

  • --update-name (boolean, optional): Rename the linked project to match tessl.json

  • --yes / -y (boolean, optional): Confirm and apply requested repair

Notes

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

tessl project list

List all projects in a workspace.

Usage

Flags

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

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

Notes

  • Shows every project you can access in the selected workspace, with its name, ID, and source.

  • The workspace is resolved in this order: --workspace, the TESSL_WORKSPACE environment variable, the project linked in tessl.json, then the workspace prefix in a .tessl-plugin/plugin.json when no tessl.json exists. If none of those apply and you belong to more than one workspace, you are prompted to pick one, or must pass --workspace in a non-interactive shell.

Examples

Project dependencies

tessl install

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

Alias: tessl i

Usage

Arguments

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

    • Registry plugin: workspace/plugin[@version] (version optional, defaults to latest)

    • GitHub repository:

      • Full URL: https://github.com/owner/repo

      • Shorthand: github:owner/repo (e.g., github:softaworks/agent-toolkit)

    • File path: file:<path> to install from local directory

Flags

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

  • --skill (string, repeatable, optional): Select specific skills to install from GitHub repositories. Used when a repository contains multiple skills. If omitted, you'll be prompted interactively to select from available skills. Can be specified multiple times to install multiple skills from the same repository.

  • --yes (boolean, optional): Skip confirmation prompts and auto-select all skills

  • --verbose / -v (boolean, optional): Show detailed warning messages during installation

  • --watch-local (boolean, optional): Watch local file-source plugins and reinstall on changes

  • --accept-warnings (boolean, optional): Pre-accept install policy warnings (no interactive prompt)

  • --strict (boolean, optional): Fail if a version is too new rather than installing an older fallback

  • --agent (string, optional, repeatable): Override agents to install for. Supported values: claude-code, cursor, gemini, antigravity, codex, openhands, openclaw, copilot, copilot-vscode, agents, tessl-agent.

Notes

  • Plugins are installed to .tessl/plugins/<plugin-name>/ in your repository (or ~/.tessl/plugins/ when using --global)

  • Your repository's tessl.json is automatically updated with the plugin reference

  • If a plugin is already installed and up-to-date, it will be skipped

  • GitHub URL formats: https://github.com/owner/repo, github:owner/repo, or with branch/path: https://github.com/owner/repo/tree/main/skills/pdf

  • File system installation: Use file:<path> to install from a local directory (.tessl-plugin/plugin.json expected in the path)

  • Install policy warnings: If a plugin triggers install policy warnings (such as critical or high Snyk security findings), you will be asked for permission before installation continues. You can always choose to proceed — installation is never blocked. Use --accept-warnings to pre-accept these warnings and skip the prompt.

Examples

tessl search

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

Usage

Flags

  • --global / -g (boolean, optional): Install selected plugins and skills globally to ~/.tessl/ instead of the current project

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

  • --org (string, optional): Limit results to an organization you can access, identified by its slug or ID

  • --workspace (string, optional): Limit results to a workspace you can access, identified by org/workspace or its ID

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

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

Arguments

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

Examples

tessl uninstall

Uninstall plugins from your repository.

Usage

Arguments

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

Flags

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

  • --skill (string, repeatable, optional): Remove specific skills instead of the entire plugin (repeatable)

Notes

  • Removes the plugin from tessl.json and deletes files from .tessl/plugins/

  • Does not require authentication (local operation only)

Examples

tessl list

List all installed plugins in your repository.

Usage

Flags

  • --global / -g (boolean, optional): List plugins installed in global ~/.tessl/ instead of the current repository

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

Notes

  • Lists all plugins installed in your repository based on tessl.json

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

  • Does not require authentication (local operation only)

Examples

tessl outdated

Check for available plugin updates.

Usage

Flags

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

Examples

tessl update

Update plugins to newer versions.

Usage

Flags

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

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

  • --global / -g (boolean, optional): Update plugins installed globally in ~/.tessl/ instead of the current repository

  • --accept-warnings (boolean, optional): Pre-accept install policy warnings (no interactive prompt)

  • --agent (string, optional, repeatable): Override agents to sync for. Supported values: claude-code, cursor, gemini, antigravity, codex, openhands, openclaw, copilot, copilot-vscode, agents, tessl-agent.

Arguments

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

Notes

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

Examples

Skill management

tessl skill new

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

Usage

Flags

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

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

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

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

  • --install (boolean, optional): Automatically install in the current repository after creation

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

Notes

  • If flags are omitted, an interactive wizard will guide you through skill creation

  • The skill will be created as a directory with the proper Agent Skills specification structure

  • Use --install to immediately add the skill to your local agent configuration

Examples

tessl skill import

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

Usage

Flags

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

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

  • --force (boolean, optional): Overwrite existing .tessl-plugin/plugin.json without prompting

Arguments

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

Examples

tessl skill lint

Validate skill structure and contents.

Usage

Arguments

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

Notes

  • Checks for required files and proper structure

  • Validates frontmatter fields (name, description, etc.)

  • Verifies conformance to the Agent Skills specification at agentskills.io/specification

  • Returns validation errors and warnings

Examples

tessl skill publish

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

Usage

Flags

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

  • --public (boolean, optional): Make skill public (used if importing)

  • --force (boolean, optional): Overwrite existing .tessl-plugin/plugin.json without prompting

  • --bump (string, optional): Auto-bump version if it already exists in the registry. Supported values: patch, minor, major

  • --dry-run (boolean, optional): Run all pre-publish checks without publishing

  • --skip-evals (boolean, optional): Skip publishing eval scenarios from evals/ directory

  • --with-scenario-quality-check (boolean, optional): Exclude misleading scenarios from the publish-time eval run

  • --eval-scenarios (string, optional): Path to eval scenarios directory (default: <path>/evals)

  • --resolve-symlinks (boolean, optional): Resolve symlinked files to their target contents when packing

Arguments

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

Notes

  • Skills are automatically linted before publishing

  • Published skills are versioned based on the version in the skill manifest

  • Eval scenarios from the evals/ directory are published by default; use --skip-evals to exclude them

  • Automatic evaluation: When published, skills are automatically evaluated and review scores are calculated (see Check a skill's quality using review)

Examples

tessl skill unpublish

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

Skills are published inside a plugin. To remove a published skill, delete the skill and republish the plugin, unpublish the plugin, or archive the plugin. See tessl plugin unpublish and tessl plugin archive.

Tessl Review

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

tessl review run

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

Usage

Flags

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

  • --workspace / -w (string, optional): Workspace name or ID. Required when --json is set

  • --threshold (number, optional): Exit non-zero if the review score is below this percentage. 0 never fails (skips validation and score gating)

  • --label / -l (string, optional): Label to describe this review run

  • --force / -f (boolean, optional): Run a fresh review even when cached results exist

  • --review-plugin (string, optional): Reviewer plugin — a path to a local plugin directory, or a registry ref workspace/plugin[@version]. Requires a paid plan; on a Free organisation, passing this flag returns an upgrade error

  • --wait / --no-wait (boolean, optional): Wait for the review to finish before returning (default: wait; use --no-wait to submit and return the run id immediately, then reconnect with tessl review view). Cannot be combined with --threshold, which needs the completed score

Arguments

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

Notes

  • Requires authentication; sign in with tessl login or set the TESSL_TOKEN API key in the environment

  • --workspace is required when --json is set, since non-interactive runs cannot prompt for a workspace

  • The command polls until the review completes, then prints the results

  • --threshold causes a non-zero exit when the score falls below the percentage, making it a CI gate

  • Press Ctrl+C to detach — the review continues server-side and can be viewed later with tessl review view

  • run has two subcommands: quality (the default, documented here) and security (below). tessl review run quality is the explicit form of the default

Examples

tessl review run security

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

Usage

Flags

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

  • --workspace / -w (string, optional): Workspace name or ID. Required when --json is set

  • --label / -l (string, optional): Label to describe this security review run

  • --force / -f (boolean, optional): Run a fresh scan even when cached results exist

  • --fail-on (string, optional): Exit non-zero if the highest severity is at or above this level: low, medium, high, critical

  • --wait / --no-wait (boolean, optional): Wait for the scan to finish before returning (default: wait; use --no-wait to submit and return the run id immediately, then reconnect with tessl review view). Cannot be combined with --fail-on, which needs the completed findings

Arguments

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

Notes

  • Requires authentication; sign in with tessl login or set the TESSL_TOKEN API key in the environment

  • The scan runs server-side; the command polls until it completes, then prints the findings and the highest severity

  • --fail-on gates the exit code on severity, making it a CI gate — the security equivalent of --threshold on a quality review

Examples

tessl review view

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

Usage

Flags

  • --json (boolean, optional): Output as JSON, in the same shape as tessl review run --json

  • --last (boolean, optional): View results for the most recent review run

  • --threshold (number, optional): Quality reviews only. Exit non-zero if the review score is below this percentage (0-100)

  • --fail-on (string, optional): Security reviews only. Exit non-zero if the highest severity is at or above this level: low, medium, high, critical

  • --workspace / -w (string, optional): Workspace name or ID. Only applies with --last; an explicit review run ID already identifies its workspace.

Arguments

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

Notes

  • Provide a review run ID or use --last; one is required

  • The gate flag follows the run's kind: --threshold gates a quality run, --fail-on gates a security run. Passing the flag for the other kind is a usage error

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

Examples

tessl review list

List recent review runs.

Usage

Flags

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

  • --limit (number, optional): Maximum number of review runs to display (default: 20)

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

Examples

tessl review retry

Re-run a failed review run.

Usage

Flags

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

  • --workspace / -w (string, optional): Workspace name or ID. Only applies with --last; an explicit review run ID already identifies its workspace.

  • --last (boolean, optional): Retry the most recent review run

Arguments

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

Notes

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

Examples

tessl review fix

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

Usage

Flags

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

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

  • --threshold (number, optional): Stop once a review scores at or above this percentage (0-100, default 90)

  • --max-iterations (number, optional): Maximum improve→review iterations to attempt (1-10, default 3)

  • --yes / -y (boolean, optional): Apply the improved skill without confirmation

  • --review-plugin (string, optional): Reviewer plugin — a path to a local plugin directory, or a registry ref workspace/plugin[@version]. Requires a paid plan; on a Free organisation, passing this flag returns an upgrade error

Arguments

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

Notes

  • Requires authentication; sign in with tessl login or set the TESSL_TOKEN API key in the environment

  • --workspace is required when --json is set, since non-interactive runs cannot prompt for a workspace

  • Runs an asynchronous improve→review loop, stopping early once --threshold is met

Examples

Plugin management

tessl plugin new

Create a new plugin with an interactive wizard.

Usage

Flags

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

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

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

  • --rules (string, optional): Include rule by name

  • --rule-description (string, optional): Initial rule instructions to include in generated rule file

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

  • --skill (boolean, optional): Include a skill in the plugin

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

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

  • --install (boolean, optional): Automatically install in the current repository

  • --public (boolean, optional): Make plugin public (default: private)

Notes

  • Creates a new plugin directory with a basic .tessl-plugin/plugin.json template

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

  • For non-interactive use, include at least one component with --skill, --skill-name, or --rules

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

Examples

tessl plugin lint

Validate plugin structure and contents

Usage

Arguments

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

tessl plugin migrate

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

Usage

Flags

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

Arguments

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

tessl plugin pack

Package a plugin into a .tgz file.

Usage

Flags

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

Arguments

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

tessl plugin info

Show plugin details from the registry.

Usage

Arguments

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

Examples

tessl plugin publish

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

Usage

Flags

  • --dry-run (boolean, optional): Run all pre-publish checks without publishing

  • --bump (string, optional): Auto-bump version if it already exists in the registry. Supported values: patch, minor, major

  • --skip-evals (boolean, optional): Skip publishing eval scenarios from evals/ directory

  • --with-scenario-quality-check (boolean, optional): Have the backend's LLM judge filter out misleading scenarios (low feasibility, rubric leakage, low value) from the publish-time eval run. Equivalent to tessl eval run --quality-check for the eval that runs as part of publishing.

  • --workspace (string, optional): Workspace to publish under when the plugin manifest name is flat (no workspace/ prefix)

  • --version (string, optional): Version to publish when the plugin manifest omits one

  • --verbose / -v (boolean, optional): Print every archived file with the reason it was included

Arguments

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

Examples

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

tessl plugin unpublish

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

Usage

Flags

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

Notes

  • Only available within 2 days of publishing

Examples

tessl plugin archive

Archive plugins in the registry.

Usage

Flags

  • --plugin (string, optional): plugin to archive in the format workspace/plugin (archives all versions) or workspace/plugin@version (archives a single version)

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

Notes

  • Prevents new installations while preserving existing installations

Examples

Organization management

tessl org list

List all organizations that you are a member of.

Usage

tessl org usage

Show your Tessl credit usage.

Usage

Flags

  • --org (string, optional): Organization name or ID. You are prompted when you belong to several.

  • --json (boolean, optional): Output as JSON. The payload contains plan and credits fields.

Examples

Workspace management

Workspaces enable you to create private collections of plugins that are restricted to yourself or your organization. You can control member access and permissions. To learn more, see Distributing via registry.

tessl workspace create

Create a new workspace.

Usage

Flags

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

Arguments

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

Examples

tessl workspace list

List all workspaces that you are a member of.

Usage

Flags

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

Examples

tessl workspace delete

Delete an existing workspace.

Usage

Arguments

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

Examples

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

tessl workspace add-member

Add a user to a workspace with specified permissions.

Usage

Flags

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

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

  • --role (string, optional): Role to assign. Supported values: member, publisher, manager, owner

See Roles for more information

Examples

tessl workspace remove-member

Remove a user from a workspace.

Usage

Flags

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

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

Examples

tessl workspace list-members

List all members of a workspace.

Usage

Arguments

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

Examples

tessl workspace archive

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

Usage

Flags

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

Arguments

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

Notes

  • Archiving is a safer alternative to deleting, as archived workspaces can be restored

  • Use tessl workspace unarchive to restore an archived workspace

Examples

tessl workspace unarchive

Unarchive an archived workspace, making it active again.

Usage

Arguments

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

Examples

Configuration management

tessl config get

Get a configuration value or show all configuration.

Usage

Arguments

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

Examples

tessl config set

Set a configuration value.

Usage

Arguments

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

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

Examples

tessl config list

List all configuration values.

Usage

Arguments

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

Notes

  • Similar to tessl config get but specifically for listing configuration values

Examples

tessl config add

Add one or more values to a configuration array.

Usage

Arguments

  • key (string, required): Configuration key for the array

  • value (string, required, repeatable): One or more values to add to the array

Notes

  • Use this command to add values to array-type configuration settings

  • Can specify multiple values in a single command

Examples

tessl config remove

Remove a value from a configuration array.

Usage

Arguments

  • key (string, required): Configuration key for the array

  • value (string, required): Value to remove from the array

Notes

  • Use this command to remove values from array-type configuration settings

  • Only removes the specified value, not the entire configuration key

Examples

Diagnostics and utilities

tessl doctor

Run authentication and manifest diagnostics to troubleshoot issues.

Usage

Flags

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

Examples

tessl feedback

Send feedback to the Tessl team.

Usage

Arguments

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

Examples

CLI self-management

tessl cli update

Update the CLI to the latest or specified version.

Usage

Flags

  • --target / -t (string, optional): Target version to update to (example: v1.0.0)

  • --channel / -c (string, optional): Release channel to switch to. Supported values: latest, beta

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

Examples

API key management

tessl api-key create

Create an API key for a workspace.

Usage

Flags

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

  • --name (string, optional): Name for the API key

  • --role (string, optional): Role to assign. Supported values: member, publisher, manager, owner

  • --expiry-date (string, optional): Expiry date in ISO 8601 format (example: 2027-12-31T00:00:00Z). Defaults to 30 days from creation

  • --ttl (string, optional): Time until expiry as a positive whole number followed by h (hours), d (days), w (weeks), mo (30-day months), or y (365-day years), such as 3h, 4w, or 1y. Minutes are not supported. Calculated using the local clock after interactive prompts, just before the creation request. Use either --ttl or --expiry-date. Without either flag, keys expire 30 days from creation

Examples

tessl api-key list

List API keys for a workspace.

Usage

Flags

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

Examples

tessl api-key delete

Delete an API key from a workspace.

Usage

Flags

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

  • --yes / -y (boolean, optional): Skip confirmation prompt and delete immediately

Arguments

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

Examples

Environment management

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

For what belongs in an environment and how runs consume it, see Environments.

tessl env is a short alias for tessl environment. A scheduled run cannot mint its own GitHub token, so include a GITHUB_TOKEN (or GH_TOKEN) in the environment for any schedule that checks out a repository or opens pull requests.

tessl environment create

Create an environment for a workspace.

Usage

Arguments

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

Flags

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

  • --env-file (string, optional): Path to a .env file with environment variables.

  • --mcp-server (string, optional, repeatable): Name of a workspace MCP server to configure.

  • --github-access (none, read, or write, optional): GitHub access granted to runs that use this environment. The default is read.

  • --linear-access (none, read, or write, optional): Linear access granted to cloud launch runs that use this environment. The default is none.

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

For Linear access, none injects no platform credential. read permits Linear queries, while write also permits mutations. An environment cannot grant read or write while defining a non-empty LINEAR_TOKEN or LINEAR_API_URL. Tools must use LINEAR_TOKEN for authorization and LINEAR_API_URL as the API base URL; a tool that ignores LINEAR_API_URL sends the run key to Linear, which rejects it.

Examples

tessl environment list

List environments for a workspace.

Usage

Flags

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

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

Examples

tessl environment view

View metadata for an environment.

Usage

Arguments

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

Flags

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

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

Notes

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

Examples

tessl environment update

Update an environment for a workspace.

Usage

Arguments

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

Flags

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

  • --env-file (string, optional): Path to a .env file with environment variables.

  • --mcp-server (string, optional, repeatable): Name of a workspace MCP server to configure.

  • --github-access (none, read, or write, optional): GitHub access granted to runs that use this environment.

  • --linear-access (none, read, or write, optional): Linear access granted to cloud launch runs that use this environment.

  • --clear-mcp-servers (boolean, optional): Remove all MCP servers wired into this environment.

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

For Linear access, none injects no platform credential. read permits Linear queries, while write also permits mutations. An environment cannot grant read or write while defining a non-empty LINEAR_TOKEN or LINEAR_API_URL. Tools must use both injected variables: LINEAR_TOKEN for authorization and LINEAR_API_URL as the API base URL.

Notes

  • --env-file is required unless at least one --mcp-server, --github-access, or --linear-access is provided. A metadata-only update with no --env-file changes just the metadata and leaves every stored value untouched. Passing --env-file replaces the sealed values instead: the env file becomes the complete set, so it must include every credential you want to keep.

  • --clear-mcp-servers always requires --env-file, including when it is combined with --github-access, --linear-access, or --mcp-server, because clearing is treated as an update with no new MCP servers.

Examples

tessl environment delete

Delete an environment from a workspace.

Usage

Arguments

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

Flags

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

Examples

Model Context Protocol (MCP)

tessl mcp start

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

Usage

tessl mcp proxy

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

Usage

Arguments

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

Authentication

  • Interactive use — sign in once with tessl login; the proxy reuses the same credentials.

  • CI or other non-interactive contexts — set TESSL_TOKEN to a Tessl API key for the workspace. See tessl api-key create.

Examples

Repository

tessl repo select-commits

Browse recent commits in a repository and select which ones to evaluate. Used as the first step in generating codebase scenarios.

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

Usage

Arguments

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

Flags

  • --keyword (string, optional): Filter by commit message keyword

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

  • --since / --until (string, optional): Date range in YYYY-MM-DD format

  • --count / -n (number, optional): Number of commits to show (1–100)

  • --workspace / -w (string, optional): Required outside interactive mode

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

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

Examples

GitHub integration

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

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

tessl github token

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

Usage

Flags

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

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

Notes

  • The token is written to stdout so it can be captured directly, for example GH_TOKEN=$(tessl github token ...). The expiry is written to stderr, so it does not pollute that capture.

  • The minted token is a GitHub App installation token, not a user token. Installation-scoped endpoints such as /installation/repositories work; user-scoped endpoints such as gh org list fail.

  • Without --repo, the token covers everything the selected installation can reach.

Examples

tessl github setup-auth

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

Usage

Flags

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

  • --repo (string, optional, repeatable): Scope the token to a repository and select its installation by owner, in owner/name form. All values must share one owner.

  • --force (boolean, optional): Overwrite an existing gh/git auth configuration. Without it, the command stops rather than replacing one already in place.

  • --auto-refresh (boolean, optional): Spawn a background process that re-mints the token periodically, for steps that outlive a single token.

  • --refresh-interval-seconds (number, optional): How often that background process re-mints, in seconds. Defaults to 2700, which is 45 minutes.

Notes

  • Signs in gh and sets a global git identity for the bot. This persists after the command exits, so prefer an ephemeral runner or container.

  • Refuses to run when gh is already signed in or a global git identity is already set. Use --force to replace them.

  • Clear GH_TOKEN and GITHUB_TOKEN first. gh prefers a token in the environment over the credential this writes.

  • Without --auto-refresh the credential lasts until the expiry the command prints.

  • With --repo, refreshes re-mint against the same owner and repositories. Without it, each refresh picks the most recently updated installation.

Examples

Inventory

tessl inventory import

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

Usage

Flags

  • --org (string, optional): GitHub account or org to scan. Prompted if omitted.

  • --workspace (string, optional): Name or ID of workspace to upload to. Prompted if omitted.

  • --repo (string, repeatable, optional): Limit scan to this repo (repeatable)

  • --ignore-repo (string, repeatable, optional): Exclude this repo from the scan (repeatable)