Commands

Global Flags

Command Details

tome init

When using the default Tome home, interactive setup first offers Tome data folder selection. This portable root determines configuration lookup, cached repositories, the lockfile, and the default library location. Existing configuration is detected in the selected folder before setup continues, and the same folder is used for saving configuration and the post-init sync. A custom library may live elsewhere; local settings remain under ~/.config/tome.

Interactive init also offers Tome’s official using-tome agent skill, defaults to yes, and displays the equivalent command:

tome add MartinP7r/tome --subdir skills

Accepting registers MartinP7r/tome as a Git/source directory with subdir = "skills"; the post-init sync clones it immediately. --no-input omits this recommendation and performs no new network request for the official repository.

tome sync

Runs the full pipeline: resolve repository, profile, project, and local-settings layers; discover and consolidate skills; diff the lockfile; distribute through destination tag routes; and clean up stale entries. Generates tome.lock for reproducible provenance snapshots. Use tome tag and tome route to classify and route newly imported skills.

tome add

Register a Git skill repository in shared repository policy or an explicit local directory in the selected profile. Git sources are discovery-only and do not select destinations: tome add has no --to flag. Git inputs also reject --role; local paths continue to accept it. Git inputs accept either a full URL (https://github.com/owner/repo, git@github.com:owner/repo.git) or a bare GitHub slug (owner/repo), which is expanded to https://github.com/owner/repo (v0.8.2+). The clone is shallow and lives in ~/.tome/repos/<sha256>/.

Git forms

tome add https://github.com/user/skills           # full HTTPS URL
tome add user/skills                              # bare slug → github.com
tome add git@github.com:user/skills.git           # SSH URL
tome add user/skills/tree/main/skills             # /tree/<ref>/<subdir> shortcut (v0.13+)
tome add user/skills --subdir skills              # explicit --subdir flag (v0.13+)

The /tree/<ref>/<subdir> URL form mimics how GitHub renders navigation into a subdirectory in your browser — copy-paste from github.com/owner/repo/tree/main/skills and it just works. Extracted <ref> becomes the default branch; <subdir> becomes the discovery subdirectory. Explicit --branch / --subdir flags override URL-embedded values (with a warning).

Local path forms

Explicit local paths may be absolute, tilde-prefixed (~ or ~/...), or dot-relative (., .., ./..., or ../...). Bare owner/repo inputs remain GitHub slugs even if a matching path exists. The default name is the path’s final component, and local directories default to role synced. Dot-relative inputs are resolved lexically against the tome add working directory and do not depend on later commands’ working directories. Checked save serializes anchored paths outside home as absolute paths and may serialize paths under home as portable ~/...; both resolve to the same add-time location. Anchoring does not require the source to exist, canonicalize it, or resolve symlinks. Explicit ~/... inputs retain the same portable behavior.

tome add ~/.pfw/skills --role managed
tome add ./team-skills --role source --name team

Git-only --branch, --tag, --rev, and --subdir flags are rejected for local paths.

Auto-detection of common subdirs (v0.13+)

If tome sync finds zero skills at a directory’s root AND no subdir is configured, it probes common Claude Code plugin layouts (skills/, .claude-plugin/skills/) and emits a subdir = "..." hint if any candidate has skills inside. Catches the “I added a Claude plugin repo and got zero skills” case without forcing the user to know the convention up front.

Flags

--branch, --tag, --rev are mutually exclusive.

Choosing the right role (v0.14+)

The role field decides what tome does with a configured directory:

The defaults bite if you don’t know them. When you omit --role, the directory’s role falls back to its type default:

• claude-plugins → managed
• directory → synced
• git → source

The directory → synced default is the one that surprises people. If you tome add a local directory owned by a package manager (e.g. ~/.pfw/skills/), the synced default writes ~170 distribution symlinks INTO that source directory — polluting it with content tome propagated from other configured directories. Use --role source or --role managed for read-only package manager directories to keep them clean.

# WRONG (default role = synced; tome writes BACK into ~/.pfw/skills/)
tome add ~/.pfw/skills

# OK — discovery only, no write-back, but library entries get
# `managed: false` (treated as a generic local source).
tome add ~/.pfw/skills --role source

# BEST (v0.15+) — Managed semantic: library entries get `managed: true`,
# so reconcile + foreign-symlink protection recognize this as an
# external-package-manager-owned source.
tome add ~/.pfw/skills --role managed

source vs managed for flat-directory package managers (v0.15+)

Both refuse to write back into the source dir, so either keeps ~/.pfw/skills/ clean. The differences are subtle but material if you care about upstream-update semantics down the line:

For today’s needs (just propagating pfw skills to your other tools), both work equivalently. For longer-term integration with pfw’s own update lifecycle, prefer managed.

The success message now echoes the resolved role so you see what you got:

✓ Added directory 'pfw' (git: https://..., role: source)
  → Source (skills discovered here, not distributed here)

tome tag

Tags are shared library metadata stored in .tome-manifest.json:

tome tag add <skill> <tag>
tome tag remove <skill> <tag>
tome tag list [<skill>]

Tag mutation requires an existing manifest skill. New tags affect routing only after a destination selects them.

tome route

Routes belong to the active profile or to the nearest project .tome.toml that owns the destination:

tome route tag add --to <destination> <tag>
tome route tag remove --to <destination> <tag>
tome route exclude add --to <destination> <skill>
tome route exclude remove --to <destination> <skill>

Selected tags use OR matching. An explicit exclusion wins over a matching tag. Untagged skills stay library-only for destinations with configured routes.

tome profile

tome profile create <name> creates machines/<name>.toml, tome profile list lists profiles, and tome profile select <name> records the active profile in local settings.toml.

tome paperclip-agents

Explicitly materializes versioned catalog categories/use-case sets into Paperclip agents’ desired company-skill assignments. This is separate from generic tome sync target deployment: copy deployment never mutates Paperclip agents.

preview resolves one canonical catalog revision plus the selected effective constraints, reads current desired/runtime state from either a disposable state file or the Paperclip API, and renders one fleet-wide before/after impact. It does not mutate the canonical library or any Paperclip agent.

When reading live Paperclip state, Tome first uses the read-only company skill attachment route (GET /api/companies/{companyId}/skills/{skillId}) and derives each agent’s current desired skills from usedByAgents[].desired. Runtime state is optional and may be unavailable on that route. The mutating POST /api/agents/{agentId}/skills/sync endpoint is used only by apply.

tome paperclip-agents preview \
  --catalog catalog.toml \
  --assignments agents.toml \
  --current-state state.json \
  --constraint paperclip-agent

apply recomputes the same plan, requires the preview confirmation token, uses Paperclip’s desired-skill sync endpoint in replace mode, then reads every affected agent back and fails if desired/runtime state differs from the intended set. The API URL is read from --paperclip-api-url or PAPERCLIP_API_URL; the token is read from PAPERCLIP_API_KEY by default.

tome paperclip-agents apply \
  --catalog catalog.toml \
  --assignments agents.toml \
  --constraint paperclip-agent \
  --confirm apply-abc123def456

Catalog TOML is intentionally small and deterministic:

revision = "catalog-2026-10-02"

[categories.engineering]
description = "Engineering work"

[skills.using-tome]
company_skill = "using-tome"
categories = ["engineering"]
constraints = ["paperclip-agent"]

[use_case_sets.founding-engineer]
categories = ["engineering"]
constraints = ["paperclip-agent"]

Assignment TOML selects sets per agent:

[[agents]]
agent_id = "agent-id"
display_name = "FoundingEngineer"
sets = ["founding-engineer"]
constraints = ["codex"]

tome pool

tome pool exclude <skill> adds a shared discovery exclusion to repository policy. tome pool restore <skill> removes that exclusion. Pool conflict resolution also exposes accept-source and retain-current; there is no tome remove pool compatibility command.

tome remove

Split into two subcommands since v0.10 (Phase 14, D-API-2):

tome remove dir <name>

Remove a configured directory entry from its owning repository policy or selected profile. Manifest entries owned by that directory transition to Unowned (per LIB-04): library content is preserved and only the source_name linkage is cleared. Partial cleanup failures produce a non-zero summary. For Git directories, the cached clone in ~/.tome/repos/<sha256>/ is removed.

tome remove skill <name>

Delete an Unowned skill from the library entirely: clear the manifest entry, remove the library directory, remove downstream distribution symlinks, and remove the lockfile entry. Refuses to operate on Owned skills with a hint to run tome remove dir first (per D-B2).

tome reassign

Reassign a skill to a different directory — useful when the same skill appears under multiple sources and you want to pin which directory owns it. Accepts both Owned skills (re-anchor between configured directories) and Unowned skills (re-anchor a previously-stranded skill back to a configured directory, per UNOWN-01 / D-API-1).

tome fork

Fork a managed (read-only) skill into a local directory so it can be edited. The local copy supersedes the managed one in the library.

tome list

tome browse

Full-screen interactive skill browser using fuzzy search. Supports sorting, grouping by source, viewing source, and copying paths. Destination-ambiguous disable actions are unavailable; use tome route exclude add --to <destination> <skill> explicitly.

tome doctor

Diagnose library state. When run interactively (no --no-input, no --dry-run), surfaces issues and offers per-category repair prompts.

Orphan-directory repair (v0.14+)

When tome doctor finds a directory in the library that has no matching manifest entry (an “orphan”), it offers four choices per orphan:

• claim — Register the orphan in the manifest as an Unowned skill (v0.14+). Hashes the directory and writes a SkillEntry::new_unowned. Assign tags and configure a destination route before expecting routed distribution on the next tome sync.
• keep — Leave the directory on disk; tome sync will re-register it IF it discovers the orphan from a configured source. Useful when you know the orphan’s source got temporarily disconnected and will come back. Note: for library-canonical orphans with no upstream source, this option is a no-op until you claim it or add a source that covers it.
• delete — Remove the directory from disk permanently.
• skip — Leave the orphan as-is; doctor will surface it again on the next run.

Broken-frontmatter skills (v0.16+)

tome doctor walks every manifest-tracked skill and parses its SKILL.md frontmatter. Failures surface as Library Warnings — for example:

! 'my-skill' has unparsable SKILL.md frontmatter: invalid YAML frontmatter
! 'other-skill' has no SKILL.md file

These are not auto-repairable — the user must edit the SKILL.md file (or remove the skill) by hand. Without this check, the failure was only visible as a one-line stderr warning during tome sync; it now persists in the doctor surface so broken skills get triaged. Use tome lint <PATH> for a deeper per-field frontmatter audit.

Real-dir-in-target repair (v0.16+)

If a distribution directory contains a real directory (not a symlink) whose name matches a library skill, tome doctor hash-compares the two:

• Identical content — Surfaces as an auto-fixable Warning (real directory in target matches library content (should be a symlink)). The auto-repair pass deletes the real directory and replaces it with a symlink into the library. Typical cause: skills copied into the target dir manually before adopting tome, or by hand after the fact.
• Diverging content — Surfaces as a no-repair Warning (real directory in target diverges from library content — reconcile manually). The user must decide whether to overwrite the local edits, fold them back into the library, or remove the target copy.
• No matching library skill — Left alone; tome does not own un-paired directories in target dirs.

tome lint

Validates SKILL.md frontmatter: missing/mismatched names, description length, non-standard fields, Unicode tag codepoints. Exits with code 1 on errors (CI-friendly).

tome config

Normal commands resolve shared tome.toml, the selected machines/<profile>.toml, optional project .tome.toml, and local settings.toml. tome config --path prints the repository-policy path.

tome backup

Git-backed backup and restore. Subcommands:

tome eject

Removes all of tome’s symlinks from distribution directories. Reversible — run tome sync to recreate them.

tome relocate

Moves the skill library to a new path, updating symlinks in all distribution directories. Detects cross-filesystem moves and warns when target symlinks need to be re-anchored.

tome completions