Getting Started

Install the CLI, run the local stack, and prove the trust path end to end.

Toolshed is still a repo-first product. The most reliable way to use it today is to run the web app, worker, and TypeScript CLI from this repository, then exercise the core flow: publish, verify, search, install, and verify again.

Consumer flow

Build the CLI, point it at a running Toolshed API, search verified skills, install a pinned version, and locally verify the downloaded artifact.

Creator flow

Package a skill as a zip, publish it into the verification queue, poll status until the worker signs it, then confirm it appears in search.

Local dev flow

Run the web app and worker against the same TOOLSHED_DATA_DIR so the install and verification path behaves like one coherent system.

Step 1

Know what you need

You need three moving pieces for the full Toolshed workflow: the web app, the worker, and the CLI. The web app exposes the API, the worker validates and signs artifacts, and the CLI is what end users actually run to search, install, publish, and verify.

  • Node.js: required for the web app and the TypeScript CLI.
  • pnpm: required because this repo is a pnpm workspace.
  • Python: required for the worker.
  • zip: useful for packaging a skill artifact from a folder.

From the repo root, install dependencies once:

pnpm install
cd apps/worker && python -m venv .venv && . .venv/bin/activate && pip install -U pip && pip install -e .

If you only want the happy-path demo, the canonical shortcut is:

pnpm smoke:e2e

That script builds the CLI and web app, starts the web app and worker, publishes a temporary skill, installs it into an isolated CLI home, and finishes with node packages/cli-ts/bin/toolshed.js verify.

Step 2

Bring up the fastest working local setup

The most practical developer setup uses an isolated temporary data directory and an isolated CLI home. That keeps previous installs and stale local state from contaminating verification results.

rm -rf /tmp/toolshed-local
mkdir -p /tmp/toolshed-local/{data,home/.toolshed,skill}

cat > /tmp/toolshed-local/home/.toolshed/config.json <<'EOF'
{
  "apiKey": "ts_smoketest_12345678"
}
EOF

Build the CLI and web app from the repo root:

pnpm --filter @toolshed/cli build
pnpm --filter toolshed-web build

Start the web app in one shell:

cd apps/web
PORT=3310 HOST=127.0.0.1 TOOLSHED_DATA_DIR=/tmp/toolshed-local/data pnpm start

Start the worker in a second shell, pointing it at the exact same data directory:

cd apps/worker
TOOLSHED_DATA_DIR=/tmp/toolshed-local/data python worker.py

The shared TOOLSHED_DATA_DIR is not optional. If the web app and worker write to different locations, jobs will be created in one place and processed in another, which breaks the flow.

Step 3

Use the CLI as a consumer

The CLI currently supports login, search, install, verify, remove, publish, and status. In practice, the safest usage pattern is: search for a skill, install a pinned version, then immediately verify your local installs.

The repo does not yet document a public package-manager install path for the CLI, so the working local invocation is to run the packaged bin directly:

HOME=/tmp/toolshed-local/home \
TOOLSHED_API_URL=http://127.0.0.1:3310/api \
node packages/cli-ts/bin/toolshed.js  search "meeting notes markdown"

Install a verified version explicitly:

HOME=/tmp/toolshed-local/home \
TOOLSHED_API_URL=http://127.0.0.1:3310/api \
node packages/cli-ts/bin/toolshed.js  install research-note-distiller@1.2.0

Then run local integrity verification:

HOME=/tmp/toolshed-local/home \
TOOLSHED_API_URL=http://127.0.0.1:3310/api \
node packages/cli-ts/bin/toolshed.js  verify

What these commands actually do

  • search calls the public search API and shows verified results with description, author, tags, JTBD context, and an install hint.
  • install resolves install metadata, downloads the artifact, manifest, and signature, verifies the signature and hash locally, extracts the zip, and records the install in ~/.toolshed/installed.json.
  • verify re-fetches the server public key context and re-checks each installed artifact hash and manifest signature on your machine.
  • remove deletes an installed version and updates local CLI state.

If you want the interactive auth prompt instead of hand-writing config.json, run:

HOME=/tmp/toolshed-local/home \
TOOLSHED_API_URL=http://127.0.0.1:3310/api \
node packages/cli-ts/bin/toolshed.js  login

The API key format is validated locally and must match ts_<token>.

Step 4

Publish your own skill and wait for verification

A publishable skill is just a zip archive. The most important file is SKILL.md. Toolshed reads metadata from that archive and uses it to create the verification job.

cat > /tmp/toolshed-local/skill/SKILL.md <<'EOF'
---
name: smoke-skill-manual
version: 1.0.0
description: Manual smoke-test fixture for install and verify.
tags: [smoke, test, local]
---

This fixture exists to validate publish, verification, search, install, and verify.
EOF

(cd /tmp/toolshed-local/skill && zip -rq /tmp/toolshed-local/smoke-skill-manual-1.0.0.zip .)

Publish the zip into the verification queue:

HOME=/tmp/toolshed-local/home \
TOOLSHED_API_URL=http://127.0.0.1:3310/api \
node packages/cli-ts/bin/toolshed.js  publish /tmp/toolshed-local/smoke-skill-manual-1.0.0.zip

The CLI will infer the skill name and version from one of three places, in this order:

  1. --name and --skill-version flags passed to publish.
  2. Frontmatter in SKILL.md, including top-level name and version.
  3. The zip filename if it follows <skill-name>-<semver>.zip.

After publish, copy the returned job id and poll until the worker finishes:

HOME=/tmp/toolshed-local/home \
TOOLSHED_API_URL=http://127.0.0.1:3310/api \
node packages/cli-ts/bin/toolshed.js  status <job-id>

When the job reaches verified, the skill should become discoverable via search and installable through the verified artifact flow.

Step 5

Understand what Toolshed writes on disk

The CLI keeps its local state under ~/.toolshed, or under whatever HOME you point it at. The important paths are:

~/.toolshed/config.json
~/.toolshed/installed.json
~/.toolshed/skills/<encoded-skill-name>/<version>/artifact.zip
~/.toolshed/skills/<encoded-skill-name>/<version>/manifest.json
~/.toolshed/skills/<encoded-skill-name>/<version>/signature.sig
~/.toolshed/skills/<encoded-skill-name>/<version>/extracted/

During install, Toolshed stores the original zip, the signed manifest, the detached signature, and an extracted copy of the artifact. That structure is what makes offline inspection and later verify possible.

Step 6

Use the practical troubleshooting checklist

  • "Not logged in": create ~/.toolshed/config.json or run node packages/cli-ts/bin/toolshed.js login inside the same HOME you are using for other commands.
  • Install works but verify fails: verify checks every installed skill in the active CLI home. Use an isolated HOME for tests so stale installs from other runs do not poison the result.
  • Publish never reaches verified: confirm the worker is running and that both the web app and worker share the same TOOLSHED_DATA_DIR.
  • Publish cannot infer name or version: add name and version to SKILL.md frontmatter or pass --name and --skill-version.
  • No search results: make sure the skill actually reached verified; unverified jobs are not installable through the normal verified flow.
  • Artifact trust mismatch: if install says signature verification failed or artifact hash mismatch, treat that as a real integrity failure, not a cosmetic warning.

Next Moves

Start with the smoke test if you want proof, then switch to manual commands when you want control.

The smoke test is the fastest confidence check. The manual flow is better when you are debugging packaging, worker behavior, or install verification details.

Explore verified skillsLog in to publish