CLI commands

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

👉 Closed beta notice

Tessl framework is in private beta. Join our community to be updated on our future product releases.

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

1. Create a spec: tessl create --prompt "your idea"

2. Edit any file (spec, code, test) : tessl edit your-file --prompt "your changes"

3. Build implementation and run any tests: tessl build your-spec.md

4. Build and run new tests for your spec: tessl build-tests your-spec.md

5. 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-tests (string[], optional): Control which test files to generate. Options: "never", "missing", "outdated", "dirty", "always". Can combine multiple options. Default: ["missing", "outdated", "dirty"]. Note: locked tests are always skipped regardless of this setting.

• 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

The generate-tests parameter controls which test files to generate. Locked tests (marked with .locked class) are always protected and cannot be regenerated regardless of this setting.

Example

tessl build-tests 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 test (positional argument).

• test-command (string): The command to use to run any associated tests. '{files}' will be substituted with the spec's test paths.

• timeout-secs (number): Number of seconds to wait before timing out overall test execution [number]

• inactivity-timeout-secs (number): Number of seconds of test inactivity before timing out [number]

Example

tessl test specs/calculator/calculator.spec.md --test-command 'npx vitest {files}'

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.

Omitting both code and spec parameters will run document on any specs with generated code which has been manually changed since generation, or which point to uncontrolled code files with a @describe link.

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
tessl document --include-impl-details

---

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

Finds and installs Tiles for the dependencies declared in your project. Tessl uses your package manager to add the appropriate Tiles and updates tessl.json accordingly. If newer versions of Tiles are available, they will also be updated.

Ecosystems supported:

• JavaScript: yarn, npm, pnpm

• Java: maven, gradle

• Python: pip, poetry

Usage

tessl registry sync

tessl registry publish

Publish specs to the Tessl registry

Usage

tessl registry publish <path>

Parameters

• path (string): Path to the tile directory to publish

Examples

# Publish a tile to the registry
tessl registry publish path/to/my/tile

---

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 login

Login to Tessl. We currently support Github and Google as an identity provider

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.

Workspace Management

You can create private workspaces that enable you to store and retrieve usage specs that you want to restrict only to yourself or your organization. You can control the members who would have access and the specific permissions for each of them. To learn more, see Publish private usage specs for your libraries.

tessl workspace list

List all workspaces

tessl workspace list

tessl workspace create

Create a new workspace

Parameters

• name (string): Name for the workspace. The name must be lowercase.

tessl workspace create <name>

tessl workspace delete

Delete an existing workspace

Parameters

• name (string): Name of the workspace

tessl workspace delete <name>

tessl workspace list-members

List all members of a workspace

Parameters

• name (string): Name of the workspace

tessl workspace list-members <name>

tessl workspace add-member

Add a member to a workspace.

Parameters

• --workspace (string): Name of the workspace

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

• --role (string): viewer (install), member (install, publish) or owner (install, publish, archive, unpublish)

tessl workspace add-member --workspace <name> --user <username-or-id> --role [viewer|member|owner]

tessl workspace remove-member

Remove a member from a workspace

Parameters

• --workspace (string): Name of the workspace

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

tessl workspace remove-member --workspace <name> --user <username-or-id>

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