Getting Started

This guide walks through the first Tuff workflow: initialize a project, create or install a capability, detect drift, and validate the result.

For every command, the CLI Reference has the complete flags, scope behavior, and examples.

Before you initialize anything, tuff gives you a quick overview of the CLI:

1. Initialize Tuff

tuff init

Creates tuff.lock and optional project preferences, configures open-agents as the default agent, and scaffolds .agents/ directories, and auto-installs tuff-cli-guide, a reference skill your coding agent can read to learn Tuff commands.

See tuff init for project and global initialization.

2. Configure another agent (optional)

tuff init is enough for the default .agents/ workflow. Register another harness when you want to emit capabilities into its native directory:

tuff agent add claude
tuff agent add codex
tuff agent add cursor

To make that harness the default for later commands, run:

tuff agent set-default claude

See tuff agent for registration, defaults, aliases, and global settings.

3. Create and track your first capability

tuff create skill my-skill

Tuff creates a valid starter scaffold in .agents/skills/my-skill/, records the baseline, and starts tracking drift without requiring a separate import.

To create it for another agent explicitly:

tuff create skill my-skill --agent claude

See tuff create for skills, tools, hooks, workflows, and repeated agent selection.

If your project already has a skill under .agents/skills/, add it in place:

tuff add skill .agents/skills/existing-skill --agent open-agents

See tuff add for adopting existing files and installing from git.

4. Inspect what is installed

tuff list

tuff list shows the capability type, agent, drift status, and emitted path. See tuff list for scope and type filters.

5. Edit and detect drift

After editing .agents/skills/my-skill/SKILL.md, inspect the change:

tuff list
tuff diff my-skill

tuff list shows the capability as modified and tuff diff shows the tracked changes. See tuff diff for baseline and upstream comparisons.

If the drift is intentional and should become the new baseline:

tuff update my-skill

Commands use the configured default agent when -a/--agent is omitted. Pass -a <agent> to operate on a different agent, or repeat the flag for multiple agents. See tuff update for source-aware updates and dry runs.

For existing files that were added in place, later edits follow this same drift and update flow.

6. Install from git

tuff add skill https://github.com/pproenca/dot-skills rust-implement --agent open-agents

The command installs the selected capability, tracks the upstream revision, and records everything in the lockfile. Replace skill with tool, hook, or workflow when installing another capability type. See tuff add for local and Git source patterns.

7. Check for updates

tuff outdated
tuff update rust-implement

tuff outdated compares tracked git-backed capabilities against their latest upstream revision, and tuff update reconciles them when you are ready. See tuff outdated and tuff update.

8. Clean up a capability

Delete files Tuff generated for the default agent:

tuff delete rust-implement

If the capability was added from files you already owned, preserve those files and remove only Tuff tracking:

tuff untrack my-skill

See tuff delete and tuff untrack for explicit agent selection, global scope, and force behavior.

tuff agent remove <agent> only unregisters the agent. It does not remove capabilities.

9. CI validation

tuff check
# tuff-cli-guide    skill    open-agents    ok
# my-skill           skill    open-agents    ok

See tuff check for JSON output, failure handling, and the GitHub Actions example.

For deeper scenario walkthroughs, see the development lifecycle guide.