The tapestry CLI is a Node.js tool for Tapestry worlds. It handles the full project lifecycle: scaffolding, pack management, server control, publishing, and engine management.
Initialize a new Tapestry game project in the current directory. Creates tapestry.yaml, server.yaml, and a packs/ directory.
$ tapestry init
Initialized: midnight-bazaar
tapestry.yaml project manifest
server.yaml engine config
packs/ installed packages
.gitignore excludes packs/ from git
Install a package and its dependencies from the registry, updating the lockfile. Without an argument, installs everything declared in tapestry.yaml.
$ tapestry install @tapestry/core + @tapestry/core 0.1.0 (official) ✓ resolved 1 package, 0 transitive deps — locked.
Launch the Tapestry engine. Reads tapestry.yaml for engine channel and version, auto-pulls the image if needed, then starts the telnet + WebSocket listeners.
$ tapestry start ▸ pulling engine image (stable) … ▸ loading packs … ✓ listening on :4000 (telnet) · :4001 (WebSocket)
Stop the running Tapestry engine container in this directory.
$ tapestry stop ✓ engine stopped
Remove an installed package.
$ tapestry uninstall @tapestry/weather
Update a package — or all packages — to the latest compatible versions allowed by the manifest.
$ tapestry update @tapestry/combat-core
Show installed packages with version, type, and enabled/disabled status.
$ tapestry list @tapestry/core 0.1.0 core enabled @tapestry/example-pack 0.1.1 world enabled
enable activates a package in the engine boot order; disable removes it from the boot order without deleting files.
$ tapestry disable @tapestry/weather
⚠ pack disabled — restart the engine to apply
Show installed packages that have newer versions available in the registry.
$ tapestry outdated @tapestry/combat-core 0.1.0 → 0.2.0
Attach a local pack working copy to this project so edits are picked up without republishing — the local-development workflow for pack authors. unlink <name> detaches it and restores the registry copy on next install.
$ tapestry link ../my-pack ✓ linked @you/my-pack → ../my-pack $ tapestry link --list @you/my-pack → ../my-pack $ tapestry unlink @you/my-pack
Fetch the engine artifact for the configured mode (docker / binary / source), pinned by tapestry.yaml.
$ tapestry engine install ▸ pulling ghcr.io/tapestry-mud/tapestry:latest … ✓ engine ready (stable)
Update the engine to the configured version for the current channel.
$ tapestry engine update ✓ engine updated (stable · latest)
Show the installed engine version, mode, and image or path.
$ tapestry engine info channel stable version latest mode docker image ghcr.io/tapestry-mud/tapestry:latest
List the available engine channels published in the registry.
$ tapestry engine versions stable latest nightly edge
Search the registry by keyword. Matches name, description, and keywords.
$ tapestry search combat @tapestry/core — core systems including combat primitives
Show details for a registry package: manifest, versions, dist-tags, and dependencies.
$ tapestry info @tapestry/core
Create an account on the registry. You're logged in immediately — a session is issued on success. Your handle is your publishing scope (publish to @yourhandle/…).
$ tapestry register Handle: you Email: you@example.com Password: •••••••• ✓ Registered as you. Logged in.
Authenticate with the registry interactively (email + password). Stores a short-lived access token plus a rotating refresh token in ~/.tapestryrc (mode 0600). The CLI refreshes the access token silently, so you stay logged in without re-entering your password — re-login is only needed after ~30 days of inactivity.
$ tapestry login Email: you@example.com Password: •••••••• ✓ Logged in.
Revoke your session on the registry and remove ~/.tapestryrc. The refresh token is invalidated server-side, so the session can't be resumed.
$ tapestry logout ✓ Logged out.
Change your registry account password. Requires an active session.
$ tapestry change-password Current password: •••••••• New password: •••••••• ✓ password updated
Scaffold a new pack folder with a manifest and annotated example content.
$ tapestry create pack my-weather-extras ✓ created packs/my-weather-extras pack.yaml pack manifest content/ example entities, rooms, commands
Validate pack.yaml in the current directory — the same checks the registry runs on publish, without uploading.
$ tapestry validate ✓ manifest valid · 0 errors · 0 warnings
Build a tarball from the current pack directory for local inspection — no upload. Useful for CI artefacts or local testing.
$ tapestry pack ✓ @you/my-pack-0.2.0.tgz (18 KB)
Build and upload the current pack to the registry. Run it locally after tapestry login — or in GitHub Actions, where it authenticates automatically via OIDC trusted publishing (see below), with no stored token.
$ tapestry publish ✓ validated @you/my-pack@0.2.0 ▸ uploading … ✓ published — tapestry install @you/my-pack
Remove a package version (e.g. @you/my-pack@0.2.0) or all versions from the registry. You must own the scope.
$ tapestry unpublish @you/my-pack@0.2.0
Publish from CI with no secrets. Instead of storing a long-lived registry token, authorize a GitHub repository to publish to your scope. In a GitHub Actions workflow, tapestry publish detects the OIDC environment, exchanges a short-lived id-token for a registry access token, and publishes — nothing is stored. Grant permissions: id-token: write in the job, then register the binding once.
# .github/workflows/publish.yml permissions: contents: read id-token: write
Manage trusted publishers — the scope ← GitHub repo bindings that authorize OIDC publishing. Run as the scope owner (or an admin).
$ tapestry trust add you you/your-packs ✓ Trusted publisher #3: @you ← you/your-packs $ tapestry trust list #3 @you ← you/your-packs $ tapestry trust rm 3 ✓ Removed trusted publisher #3.
Manage dist-tags (named pointers to versions, like stable and latest) for a registry package. Setting a tag requires owner or admin rights.
$ tapestry dist-tag set @you/my-pack stable 0.2.0 ✓ @you/my-pack: stable → 0.2.0 $ tapestry dist-tag list @you/my-pack latest 0.2.0 stable 0.2.0
Manage registry presets — named bundles of an engine channel plus pinned pack versions, used to seed new projects.
$ tapestry preset set starter 0.0.1 stable '{"@tapestry/core":"0.1.0"}' $ tapestry preset delete starter