Spec Viewer CLI for Claude Code

Paste https://docs.specs.wseng.ai/llms.txt into Claude Code and follow the steps in order. Install is GitHub Packages only. There is no public npm package and no hosted binary.

The viewer host is https://specs.wseng.ai. This documentation site is not the viewer.

Prerequisites

You need gh (GitHub CLI) and Node 22 or newer.

Install

A default gh auth login does not grant read:packages. Refresh the token first:

gh auth refresh -h github.com -s read:packages

Point npm at GitHub Packages for the @trilogy-group scope, using that token, then install:

npm config set @trilogy-group:registry https://npm.pkg.github.com
npm config set //npm.pkg.github.com/:_authToken "$(gh auth token)"
npm install -g @trilogy-group/wsspec

wsspec auth login

This opens a browser for Cognito OAuth. The session is stored in ~/.wsspec and reused. The CLI talks to https://api.specs.wseng.ai by default.

Publish markdown

Publish into the caller's personal One-Off Specs project (@me). Arrange markdown work as folders with an index markdown file:

skills/<name>/index.md

Use the same shape for other kinds (brainlifts/<name>/index.md, examples/<name>/index.md). A document title is the YAML front-matter title: or name:, otherwise the first # H1, otherwise the filename. Nested folders become navigation folders. Upload accepts .md, images (.png .jpg .jpeg .gif .svg .webp), .html, video (.mp4 .webm), .txt, .json, .xml, and .py.

wsspec project upload '@me' ./skills --path skills/

Publish an HTML report

Upload a lone .html file. Do not also upload an index.md that links the HTML: same-batch markdown that references the HTML keeps it an asset and no viewable document is created.

wsspec project upload '@me' ./chart.html

The committed specification is a generated <path>.html.md wrapper, not the .html file. Human output looks like:

Committed 1 specification(s).
  https://specs.wseng.ai/private/8f2c1d40-5b6e-4a71-9c3d-2e0f7a114b93/q3-chart.html.md

Hand over the indented viewer URL from the upload transcript. Colleagues who are signed in can open it.

Comments

Given that viewer URL:

wsspec thread list "https://specs.wseng.ai/<slug>/skills/my-thing/index.md"
wsspec thread reply "https://specs.wseng.ai/<slug>/skills/my-thing/index.md" --thread-id <id> --content "your reply"

Use the Thread ID from thread list. Do not combine a viewer URL with --path.

Non-production viewer

To target a PR or integration API, set WSSPEC_API_URL and keep composing share URLs with that environment's viewer host. Both hosts must move together.

Production: viewer https://specs.wseng.ai, API https://api.specs.wseng.ai
A PR environment: viewer https://specs-pr194.wseng.rp.devfactory.com, API https://api-specs-pr194.wseng.rp.devfactory.com

export WSSPEC_API_URL=https://api-specs-pr194.wseng.rp.devfactory.com

Then run wsspec auth login against that API before uploading.