Tuff CLI Guide

Tuff is a capability lifecycle manager. It installs, versions, diffs, and validates the skills, tools, hooks, workflows, and MCP servers a repository gives its coding agents. Use these commands when the user asks about managing any of those, or when they mention "drift", "baseline", or "tuff".

Before You Start

Run tuff --version. If the command is missing, ask the user before installing anything. When they agree:

uv tool install tuffcli

If uv is not available, use brew tap kannandreams/homebrew-tuff && brew install tuff on macOS, or cargo install tuffcli where Rust is present. Avoid bare pip install: most systems refuse it as an externally-managed environment, and a virtual environment install is not on PATH afterwards.

Confirm with tuff --version before continuing. If the command is still not found, the install directory is not on PATH; ~/.local/bin is the usual one.

If the project has no tuff.lock, run tuff init before anything else. Never hand-edit tuff.lock or the files Tuff emits under a harness directory; edit the source under .agents/ and let Tuff re-emit.

Available Commands

Install

• tuff add <path> -a <agent> — install a local capability (auto-detect type)
• tuff add skill <path> [name] -a <agent> — install a skill
• tuff add tool <path> [name] -a <agent> — install a tool
• tuff add hook <path> [name] -a <agent> — install a hook
• tuff add workflow <path> [name] -a <agent> — install a workflow
• tuff add .agents/skills/<id> -a open-agents — track existing agent files in place
• tuff add <git-url> skill <name> -a <agent> — install skill from git
• tuff add <git-url> tool <name> -a <agent> — install tool from git
• tuff add <git-url> hook <name> -a <agent> — install hook from git
• tuff add skill <git-url> <name>@<version|range> -a <agent> — install a tagged release (1.2.0, ^1.2, >=1, <2); the lockfile records the tag, the requirement, and the commit
• without @, a git install records the version the source declares (version in tuff.toml, or version:/metadata.version: in SKILL.md frontmatter), shown as 1.2.0 (declared) since it is weaker than a release; a source declaring nothing records the commit SHA
• tuff create <type> <id> -a <agent> — create and track a capability
• tuff add pack <artifact.tuffpack> -a <agent> — atomically install a verified capability pack
• tuff add mcp <catalog-id|path|git-url>... -a <agent> — wire external MCP servers (catalog: filesystem, memory, github, fetch, git, time, sequentialthinking, everything, brave-search, notion, playwright, sentry, linear, context7) into each harness config; secrets stay as ${VAR} references. Prompts once per required variable at a real terminal (add --yes to skip, or it's automatic in a non-interactive shell)

Packs

• tuff pack build --name <name> — package accepted project capabilities into tuff-dist/<name>-0.1.0.tuffpack
• tuff pack build --name <name> --capability <id> --version <version> -a <agent> — build a selected project pack
• tuff pack init <name> --from-project --capability <id> — save a reusable ID-based definition under tuff-packs/
• tuff pack check [path] — validate a local source pack
• tuff pack build [path] -o <artifact.tuffpack> — build a reusable project definition or standalone source pack
• tuff pack inspect <artifact.tuffpack> — inspect verified metadata
• tuff pack verify <artifact.tuffpack> — verify metadata and every stored file
• tuff pack push <artifact.tuffpack> <registry/repository:tag> — publish exact pack bytes as an OCI artifact
• tuff pack pull <registry/repository:tag-or-digest> -o <artifact.tuffpack> — download and verify an OCI-distributed pack without overwriting an existing file
• tuff pack extract <artifact.tuffpack> -a <agent> -o <dir> — extract a runtime-native target

Inspect

• tuff list — show all installed capabilities with drift status
• tuff list --type skill — filter by capability type
• tuff list --scope global — show global scope
• tuff status — detailed status with override warnings
• tuff diff <id> — show local changes against baseline
• tuff diff <id> --upstream — show upstream changes (git sources only); for a release-pinned entry, against the newest release its requirement allows
• tuff diff <id>@<range> --upstream — preview what a different requirement would change before tuff update <id>@<range>
• tuff outdated — check all capabilities for available updates; repointed or tag missing on a release-pinned entry means the tag moved or vanished upstream, and tuff update <id> --force replaces the install with what the tag names now
• tuff mcp doctor — spawn each installed MCP server for real and verify the handshake + tool list, not just that the config entry exists

Update & Merge

• tuff update <id> --check — preview local baseline promotion or upstream changes
• tuff update <id> — accept local edits or reconcile with upstream
• tuff update <id> -a <agent> — update one recorded agent
• tuff update <id> --force — overwrite local changes with source output
• tuff update <id>@<range> — change a tag-pinned capability's requirement and move to the newest release it allows; a bare update never leaves the recorded range

CI & Validation

• tuff check — validate all capabilities (exit 1 on any failure)
• tuff check --json — machine-readable output for CI
• tuff list --json, tuff outdated --json, tuff diff <id> --json — the same rows as JSON, with the same type/target/status keys as check --json; prefer these over parsing tables

Manage

• tuff remove <id> — remove a capability
• tuff agent list — show available agent harnesses
• tuff agent add <id> — register an agent and initialize its project directory
• tuff init --global — initialize global scope

Agents

• open-agents — Codex, Cursor, OpenCode, Copilot, Gemini CLI, Roo, Cline
• claude — Claude Code

Scope

• Project (default): tuff.lock in repo root — committed with project
• Global state: XDG config/state/cache Tuff directories — available across all projects
• Project always wins when both exist

Directory Model

• .agents/skills/ — create and edit skills here (single source of truth)
• .agents/tools/ — create and edit tools here
• .agents/hooks/ — create and edit hooks here
• .agents/workflows/ — create and edit workflows here
• .agents/mcp-servers/ — generated server.toml records for external MCP servers (edit the manifest, not these)
• tuff.lock — committed capability identity and lifecycle metadata
• tuff.config.json — project preferences; tuff.lock remains the project source of truth
• No separate source directory — agent files are the source

Status Values

• clean — installed content matches baseline
• modified — local changes detected (run tuff diff <id> to see)
• missing — installed file no longer exists

Quick Cheat Sheet

tuff init                              # initialize repo and register open-agents
tuff add <path> -a open-agents         # install capability (auto-detect type)
tuff add skill <path> [name]           # install a skill explicitly
tuff add mcp github -a claude         # wire a catalog MCP server
tuff list                          # check drift
tuff diff <id>                     # see what changed
tuff check                         # CI validation
tuff outdated                      # check for updates
tuff update <id>                   # accept local edits or update from source