Manage MTHDS packages

Initialize, add dependencies, lock, install, update, and validate MTHDS packages using the mthds CLI.

Process

Prerequisite: See CLI Prerequisites

1. Initialize a package

Create a METHODS.toml manifest:

mthds package init --directory <pkg-dir>

Use --force to overwrite an existing manifest:

mthds package init --force --directory <pkg-dir>

2. Configure exports

Exports declare which pipes the package makes available to consumers. They are organized by domain in METHODS.toml :

[exports.restaurant_analysis] pipes = ["present_restaurant", "extract_menu", "analyze_menu"]

To configure exports:

• Read the .mthds bundle(s) in the package to find the domain codes and pipe codes defined inside them

• Edit METHODS.toml to add an [exports.<domain>] section for each domain, listing the pipe codes to export

Rules:

• The main_pipe of each bundle is auto-exported — you do not need to list it unless you want to be explicit

• Concepts are always public and do not need to be listed in exports

• Each [exports.<domain>] section requires a pipes key with a list of pipe code strings

3. Add dependencies

Add a dependency to the manifest:

mthds package add <address> --directory <pkg-dir>

Options:

Flag Purpose Example

--alias

Set a local alias for the dependency mthds package add github.com/org/repo --alias mylib --directory <pkg-dir>

--version

Pin a specific version mthds package add github.com/org/repo --version 1.2.0 --directory <pkg-dir>

--path

Use a local path dependency mthds package add ./local-pkg --path --directory <pkg-dir>

4. Lock dependencies

Resolve all dependencies and generate a lockfile:

mthds package lock --directory <pkg-dir>

5. Install from lockfile

Install dependencies from the existing lockfile:

mthds package install --directory <pkg-dir>

6. Update dependencies

Re-resolve dependencies and update the lockfile:

mthds package update --directory <pkg-dir>

7. List package manifest

Display the current package manifest:

mthds package list --directory <pkg-dir>

8. Validate package manifest

Validate the METHODS.toml package manifest:

mthds package validate --directory <pkg-dir>

Options:

Flag Purpose Example

--all

Validate all packages in the workspace mthds package validate --all --directory <pkg-dir>

--runner / -r

Specify the runner for validation mthds package validate --all -r pipelex --directory <pkg-dir>

Target a specific package:

mthds package validate <target> --directory <pkg-dir>

Note: mthds package validate validates the METHODS.toml package manifest. To validate .mthds bundle semantics, use mthds-agent pipelex validate (see /check skill).

The --directory option

All mthds package commands accept --directory <path> (short: -d ) to target a package directory other than the shell's current working directory. This is essential when the agent's CWD differs from the package location.

From any directory, target a specific package

mthds package init --directory mthds-wip/restaurant_presenter/ mthds package validate --directory mthds-wip/restaurant_presenter/

If --directory is omitted, commands default to the current working directory.

Common Workflows

Starting a new package:

• mthds package init --directory <pkg-dir> — create the manifest

• Read .mthds bundles in the package to extract domain codes and pipe codes

• Edit METHODS.toml to set the correct address, description, and [exports.<domain>] sections

• mthds package validate --directory <pkg-dir> — validate the manifest

Adding dependencies to an existing package:

• mthds package add <address> --directory <pkg-dir> — add the dependency

• mthds package lock --directory <pkg-dir> — resolve and lock

• mthds package install --directory <pkg-dir> — install from lockfile

Updating dependencies:

• mthds package update --directory <pkg-dir> — re-resolve and update lockfile

• mthds package install --directory <pkg-dir> — install updated deps

Reference

• CLI Prerequisites — read at skill start to check CLI availability

• Error Handling — read when CLI returns an error to determine recovery

• MTHDS Agent Guide — read for CLI command syntax or output format details