CLI commands

Overview of Tessl's tools for creating, editing, and managing specs.

👉 Closed beta notice

The full framework is currently part of Tessl’s closed beta program. You can request access here.

Tools are functions that take in a set of parameters and execute a task on your specs. They perform specific actions on your specs, from creating and editing specs to generating code and running tests. This page provides a comprehensive reference for all Tessl tools.

Overview

Create a spec: tessl create --prompt "your idea"
Edit any file (spec, code, test) : tessl edit your-file --prompt "your changes"
Build implementation and run any tests: tessl build your-spec.md
Build and run new tests for your spec: tessl build-tests your-spec.md
Document existing code: tessl document --code existing-file.js

Getting started

tessl help

To see all available tools and commands, you can run:

tessl --help

To get detailed information about a specific tool, use the --help flag with that tool:

tessl <tool-name> --help

Common behaviors

All tools share the following behaviors:

Spec resolution: Tools that take a spec path will resolve [@use] and standard markdown links to any file type (recursively) and include those file contents as context.
Prompt parameter: Unless obviously irrelevant, every tool takes a prompt parameter describing the action you want performed (e.g., "write the capabilities section for a palindrome detector").
Additional files: Unless obviously irrelevant, every tool takes a --context parameter that provides a list of additional files to consider as context.

Spec authoring

Note: while you can use the CLI commands, we recommend using Tessl via MCP in your agent.

`tessl create`

Create a new spec from a natural language prompt.

Usage

tessl create --prompt <description>

Parameters

prompt (string): A short description of what you want to build.
spec (string, optional): Path to the spec to be created. Must be a .spec.md file. If none is provided, one will be inferred from the prompt.
context (string[], optional): Paths of any additional files that should be considered as context during generation.
force (boolean, optional): Whether to overwrite the spec if it already exists.

Example

tessl create --prompt "create a user authentication system" --spec specs/auth/auth.spec.md

`tessl edit`

Edit a spec, code file, or test implementation based on a natural language prompt.

You can enable iterative fixes to ensure code passes the tests by defining a --test-command and --max-iterations.

Usage

tessl edit <file> --prompt <description>

Parameters

file (string): Path to the file to edit (positional argument).
prompt (string): Description of the desired change.
context (string[], optional): Paths of any additional files that should be considered as context during the edit.
document-unknown-files (string, optional): Whether to automatically run tessl document for code files we don't have specs for. Options: "always" (default) or "never".
max-iterations (number, optional): Max improvement passes to attempt to fix tests after generating code and/or tests (default: 0).
test-command (string, optional): Command to use for running tests (e.g., "npm run test", "pytest").
specify-missing-dependencies (boolean, optional): If true, automatically add missing dependencies to the spec if they are used in generated code file (default: false).

Editing a spec:

tessl edit specs/calculator/calculator.spec.md --prompt "Add support for square root operations"

Editing a test file:

tessl edit tests/calculator.test.js --prompt "Add edge case tests for division by zero"

You can also omit the flags when running the tool and the command will interactively ask for any parameters that are required.

`tessl build`

Generate or refresh code for each [@generate] link in the spec and runs any existing tests. If no spec is provided, all project specs will be built.

You can enable iterative fixes to ensure code passes the tests by defining a --test-command and --max-iterations.

Usage

tessl build <path>

Parameters

spec (string, optional): Path to the spec file to build. If omitted, all project specs will be built (positional argument).
max-iterations (number, optional): Max improvement passes to attempt to fix generated code (default: 0).
test-command (string, optional): Command to use for running tests (e.g., "npm run test", "pytest").
generate-code (string[], optional): Control which files to generate. Options: "never", "missing", "outdated", "dirty", "always". Can combine multiple options. Default: ["missing", "outdated", "dirty"].
context (string[], optional): Paths of any additional files that should be considered as context during generation.
specify-missing-dependencies (boolean, optional): If true, automatically add missing dependencies to the spec when verify-deps finds violations (default: false).

Generation Control Option Meanings:

"missing": Generate files that did not exist
"outdated": Generate files when the spec has changed but the code file remains unmodified
"dirty": Generate files which were manually modified since the last time they were generated
"always": Generate files regardless of their current state
"never": Skip generating files

Example

tessl build specs/calculator/calculator.spec.md

`tessl build-tests`

Generate tests for [@test] links in the spec without generating code. Focuses specifically on test generation and running existing tests. If no spec is provided, all project specs will be processed.

You can enable iterative fixes to ensure code passes the tests by defining a --test-command and --max-iterations.

Usage

tessl build-tests <path>

Parameters

spec (string, optional): Path to the spec file to build tests for. If omitted, all project specs will be processed (positional argument).
max-iterations (number, optional): Max improvement passes to attempt to fix generated tests (default: 0).
test-command (string, optional): Command to use for running tests (e.g., "npm run test", "pytest").
generate-draft-tests (string[], optional): Control which files to generate for draft/untagged tests. Options: "never", "missing", "outdated", "dirty", "always". Can combine multiple options. Default: ["missing", "outdated"].
generate-locked-tests (string[], optional): Control which files to generate for locked tests. Options: "never", "missing", "outdated", "dirty", "always". Can combine multiple options. Default: ["missing"].
generate-impl-tests (string[], optional): Control which files to generate for implementation tests. Options: "never", "missing", "outdated", "dirty", "always". Can combine multiple options. Default: ["missing", "outdated", "dirty"].
context (string[], optional): Paths of any additional files that should be considered as context during generation.

Generation Control Option Meanings:

"missing": Generate files that did not exist
"outdated": Generate files when the spec has changed but the code file remains unmodified
"dirty": Generate files which were manually modified since the last time they were generated
"always": Generate files regardless of their current state
"never": Skip generating files

Test Generation Control Parameters

These parameters control which test files to generate based on test type (see Spec Syntax for test type details).

Example

tessl build-tests specs/calculator/calculator.spec.md

`tessl test`

Run tests for the provided spec

Usage

tessl test <spec>

Parameters

spec (string): Path to the spec file to test (positional argument).
test-command (string): Command to use for running tests (e.g., "npm run test", "pytest").
regenerate-test-runner (boolean, optional): Force regeneration of the test runner (defaults to using an existing one if available).
timeout-secs (number, optional): Override test execution timeout, specified in seconds.
lock-tests (boolean, optional): Lock tests if all tests are passing (default: false).

Example

tessl test specs/calculator/calculator.spec.md

`tessl build-tests`

Generate tests for [@test] links in the spec without generating code. Focuses specifically on test generation and running existing tests. If no spec is provided, all project specs will be processed.

You can enable iterative fixes to ensure code passes the tests by defining a --test-command and --max-iterations.

Usage

tessl build-tests --spec <path>

Parameters

spec (string[]): Path to the spec file or files to build. If omitted, all project specs will be built.
max-iterations (number, optional): Max improvement passes per file (default: 1).
context (array, optional): Paths of any additional files that should be considered as context during generation
test-command (string, optional): The command to use to run any associated tests
generate-draft-tests (enum, optional): Controls which draft tests to generate. Options: "outdated" (generates draft tests when the spec has changed but the code has not), "never", "missing" (generates draft tests when they are not found), "dirty" (generates draft tests when they are have been manually modified since last generation), "always". Defaults to missing and outdated files.
generate-locked-tests (enum, optional): Controls which locked tests to generate. Options: "outdated" (generates locked tests when the spec has changed but the code has not), "never", "missing" (generates locked tests when they are not found), "dirty" (generates locked tests when they are have been manually modified since last generation), "always". Defaults to missing files.
generate-impl-tests (enum, optional): Controls which impl tests to generate. Options: "outdated" (generates impl tests when the spec has changed but the code has not), "never", "missing" (generates impl tests when they are not found), "dirty" (generates impl tests when they are have been manually modified since last generation), "always". Defaults to missing, outdated and dirty files.

Example

tessl build-tests --spec specs/calculator/calculator.spec.md

`tessl test`

Run tests for the provided spec

Usage

tessl test <path>

Parameters

spec (string): Path to the spec file to build. If omitted, all project specs will be built.
regenerate-test-runner (boolean, optional): Force regeneration of the test runner (defaults to using an existing one if available)
timeout-secs (string, optional): Override test execution timeout, specified in seconds
test-command (string, optional): The command to use to run any associated tests

Example

tessl test specs/calculator/calculator.spec.md

`tessl document`

Creates or updates specification files to document existing code functionality. This command serves two main purposes: creating new specs from existing code files (useful for documenting legacy code or code written outside the spec-driven workflow), and locking existing specs with precise implementation details.

For code files without specs, it creates new specification files with @describe links that capture the functional requirements and behavior. For existing specs with @generate links, it can lock them with granular implementation details using the --include-impl-details flag, preserving specific behaviors that aren't captured in the original specification.

Usage

# Create/update spec from code
tessl document --code <path>

# Lock spec to implementation details
tessl document --spec <spec> --include-impl-details

# Process all tracked files
tessl document
tessl document --include-impl-details

Parameters

code (string, optional): Path to the code file to document.
spec (string, optional): Path to the spec file.
prompt (string, optional): Additional instructions on how to create or update the spec document.
context (string[], optional): Paths of any additional files that should be considered as context during generation.
include-impl-details (boolean, optional): Lock an existing spec to a code generation by adding highly granular details as .impl content. Must be used for a @generate spec link to a code file.

Examples

# Create spec from existing code
tessl document --code src/utils/helper.js --spec specs/helper/helper.spec.md

# Lock spec to capture implementation details
tessl document --spec specs/helper/helper.spec.md --include-impl-details

# Create spec with additional context
tessl document --code src/auth.js --prompt "focus on security aspects" --context config/auth.json

# Process all tracked files in the project
tessl document                                    # Re-generates ALL specs with @describe links (overwrites specs!)
tessl document --include-impl-details            # Locks ALL specs with @generate links to their current implementation

Usage Specs

`tessl registry install`

Install usage specs into your project

Usage

tessl registry install <name>

Parameters

name (string): The full name of the usage spec e.g. "tessl/[email protected]". The version (e.g. '@5.38.0`) is optional; if omitted, the latest version will be used

Examples

# Install the tessl usage spec for svelte version 5.38.0
tessl registry install tessl/[email protected]

`tessl registry search`

Search Tessl's Spec Registry for usage specs, by name, package-url, or package registry web url

Usage

tessl registry search <name>

Parameters

name (string): A name, package-url, or package registry web url

Examples

# Search for usage specs for svelte
tessl registry search svelte

`tessl registry sync`

Check for newer versions of all usage specs and install them into your project

Usage

tessl registry sync

Examples

# Upgrade your project's usage specs
tessl registry sync

Usage Specs

`tessl registry install`

Install usage specs into your project

Usage

tessl registry install <name>

Parameters

name (string): The full name of the package e.g. "tessl/[email protected]". The version (e.g. '@5.38.0') is optional; if omitted, the latest version will be used.

Examples

# Install the tessl usage spec for svelte version 5.38.0
tessl registry install tessl/[email protected]

`tessl registry search`

Search Tessl's Spec Registry for usage specs, by name, package-url, or package registry web url

Usage

tessl registry search <name>

Parameters

name (string): A name, package-url, or package registry web url.

Examples

# Search for usage specs for svelte
tessl registry search svelte

`tessl registry sync`

Check for newer versions of usage spec and install them into your project

Usage

tessl registry sync

Examples

# Upgrade your project's usage specs
tessl registry sync

`tessl registry publish`

Publish specs to the Tessl registry

Usage

tessl registry publish <path>

Parameters

path (string): Path to the spec file to publish.

Examples

# Publish a spec to the registry
tessl registry publish specs/my-package/my-spec.spec.md

Helper commands

`tessl status`

Checks specs for errors and suggests fixes. By default, lists all specs in the project and includes sync checks to detect whether each spec's code and tests are up to date with the specification.

Usage

tessl status [<path>]

Parameters

spec (string, optional): Path to a specific spec being checked, relative to the project root (positional argument).

Examples

# Check all specs in the project (default behavior)
tessl status

# Check a specific spec file
tessl status specs/calculator/calculator.spec.md

tessl mcp

Runs the mcp server command. Should not be called directly , only through an agent.

Authentication commands

tessl whoami

Show Tessl authentication status and email + tessl-user-id

tessl logout

Logout from Tessl

Setup commands

tessl setup agent

See Guided setup

Note: The setup language command has been removed in v0.19.0. Tools that require test commands now use a --test-command flag instead.

tessl setup mcp

See Guided setup

Workspace Management

tessl workspace list

List all workspaces.

tessl workspace create

Create a new workspace.

Parameters

name (string): Name for the workspace.

tessl workspace delete

Delete an existing workspace.

Parameters

name (string): Name of the workspace.

tessl workspace list-members

List all members of a workspace.

Parameters

name (string): Name of the workspace.

tessl workspace add-member

Add a member to a workspace.

Parameters

workspace (string): Name of the workspace.
user (string): Tessl username of the user to add.
role (string): viewer (install) , member (install+publish) , admin (archive,unpublish).

tessl workspace remove-member

Remove a member from a workspace.

Parameters

workspace (string): Name of the workspace.
user (string): Tessl username to remove.

Config commands

tessl config list

List all values in the tessl config file.

tessl config get

Get a value from the tessl config file

tessl config set

Set a value in the tessl config file

tessl config unset

Remove a value from the tessl config file

Models

By default, Tessl will automatically select the right model for your tool call. If you want to override the model used, you can set the --model-name option when running a tool to one of the following:

auto (default)
anthropic-reasoning (a recent Anthropic reasoning model)
openai-reasoning (a recent OpenAI reasoning model)

Exit codes

The codebase follows a consistent pattern:

0 (SUCCESS) - All operations completed successfully
1 (FAILURE) - Standard error/failure condition
144 - Critical startup/initialization error
145 - Legal/terms acceptance required

PreviousGuided setup NextMCP tools

Last updated 2 minutes ago

Overview

Getting started

tessl help

Common behaviors

Spec authoring

tessl create

tessl edit

tessl build

tessl build-tests

tessl test

tessl build-tests

tessl test

tessl document

Usage Specs

tessl registry install

tessl registry search

tessl registry sync

Usage Specs

tessl registry install

tessl registry search

tessl registry sync

tessl registry publish

Helper commands

tessl status

tessl mcp

Authentication commands

tessl login

tessl whoami

tessl logout

Setup commands

tessl setup agent

tessl setup mcp

Workspace Management

tessl workspace list

tessl workspace create

tessl workspace delete

tessl workspace list-members

tessl workspace add-member

tessl workspace remove-member

Config commands

tessl config list

tessl config get

tessl config set

tessl config unset

Models

Exit codes

`tessl create`

`tessl edit`

`tessl build`

`tessl build-tests`

`tessl test`

`tessl build-tests`

`tessl test`

`tessl document`

`tessl registry install`

`tessl registry search`

`tessl registry sync`

`tessl registry install`

`tessl registry search`

`tessl registry sync`

`tessl registry publish`

`tessl status`