Publish private usage specs for your libraries

In this tutorial we'll help you create a usage spec for a private library and share it with other Tessl users.

The (public) Spec Registry only contains usage specs for open-source dependencies. Private usage specs let you create a usage spec for code that is private to you. You can store these specs in a private workspace and control who has access. You must be logged in to follow this tutorial.

Creating a new private usage spec

Running the command tessl registry publish <path> results in looking for a tile.json in the directory you are in and publishes the files in the folder that is specified in the <path>. With that in mind, let's perform the following steps:

1. Create a workspace for your team/group/company, if you've not done so already. You can find information on workspace creation here.

2. Create a tile.json file. This is the manifest for your tile, containing metadata such as name, version and entry points.

3. Create a usage spec , with the .md extension, and place it in a directory. For the following example we name it index.md. Update tile.json to reference it under the docs key

4. Run tessl registry publish path/to/my/tile, where path/to/my/tile is the directory containing your tile manifest.

5. Add members to the workspace, with the appropriate role, if you have not already, so they can access it as admin, member or viewer.

tile.json and index.md example

tile.json

{
  "name": "<workspace-name>/<spec-name>", // e.g. "mycompany/util-formatter
  "version": "<usage-spec-version>", // e.g. "0.0.1"
  "docs": "<spec file>.md", // e.g. "index.md"
  "describes": "<package-url>", // e.g. "pkg:github/myname/util-formatter"
  "summary": "<brief-description>", // e.g. ""A colorful logging formatter for pretty terminal output."
  "private": true
}

describes must be a valid package-url and version must be valid semver

index.md

# Formatter Util

A colorful logging formatter for pretty terminal output.

## Package Information

- **Package Name**: util-formatter
- **Language**: Python
- **Installation**: `pip install git+https://github.com/<username>/<repo>.git`
- **Requirements**: Python 3.8+

## Core Imports

```python
from util_log_formatter import format_log
from util_log_formatter.formatter import ColorLogFormatter
```

## Usage

### Use as a print formatter

```python
from util_log_formatter import format_log

print(format_log("info", "Server started"))
print(format_log("warning", "High memory usage"))
print(format_log("error", "Something went wrong"))
```

### Use as a logging formatter

```python
import logging
from util_log_formatter.formatter import ColorLogFormatter

logger = logging.getLogger("myapp")
handler = logging.StreamHandler()
handler.setFormatter(ColorLogFormatter())
logger.addHandler(handler)
logger.setLevel(logging.INFO)

logger.info("Application started")
```

Sharing a usage spec

Add a Tessl user to your workspace to share private specs with them. The viewer role gives read-only access to the specs in the workspace.

tessl workspace add-member --user <tessl-user-id> --role viewer --workspace <workspace-name>

To validate if they have been added to the workspace run:

tessl workspace list <workspace-name>

The user added to a workspace will automatically have access to all usage specs published there.

Using a private usage spec

Private specs for your workspaces are searchable just like public specs.

For example, to install the util-formatter usage spec with Claude Code:

Search and install the util-formatter usage spec

Claude Code will find it in the Spec Registry and install it into your project using Tessl’s MCP tools.

Publishing a new private usage spec version

Simply raise the version and publish again.

{
  "name": "mycompany/util-formatter",
  "version": "0.0.2",
  "docs": "index.md",
  "describes": "pkg:github/myname/util-formatter",
  "summary": "A colorful logging formatter for pretty terminal output.",
  "private": true
}

Note: you currently will only find 1 version per major version in tessl search . If you make major changes, don't forget to bump the major version.

Archive or unpublish a private usage spec

To remove a usage spec from search results without deleting it, archive it with:

tessl registry archive --spec mycompany/[email protected] --reason "replaced by a new library"

This will return a message confirming that the usage spec has been archived.

Private specs can be unpublished within 2 hours of upload. Use:

tessl registry unpublish mycompany/[email protected]

This will return a message confirming that the usage spec has been unpublished.