Skillshare TUI

Development CLI for the Skillshare registry.

Examples

bun run index.ts
bun run index.ts login
bun run index.ts login local
bun run index.ts list
bun run index.ts install
bun run index.ts install "Prompt Lint"
bun run index.ts update
bun run index.ts update "Prompt Lint" --dry-run
bun run index.ts update 12 --target ./installed
bun run index.ts upload ./examples/prompt-lint --version 0.1.0
bun run index.ts install 12 0.1.0 --target ./installed
bun run index.ts install --skill-version-id 42 --target ./installed

Behavior

• Upload and publish commands show progress while scanning and reading local files, then keep a timed upload status visible until the registry call finishes.
• update reads the centralized install registry and refreshes recorded installs to the latest published registry versions.
• update can be narrowed to one skill or one target directory, and --dry-run prints planned changes without downloading or overwriting files.
• Interactive mode now checks for recorded installs with newer published versions and offers updating them before showing the main action menu.

Current TUI Flow

flowchart TD
  A[Start: skillshare] --> B{Command provided?}

  B -- No --> C[runInteractive]
  B -- Yes --> D{Which command?}

  D -->|login local| E[login LOCAL_URL]
  D -->|login| F[login PROD_URL]
  D -->|logout| G[logoutSession]
  D -->|whoami list show upload install update| H[createClient using active baseUrl]

  C --> I[resolveActiveBaseUrl]
  I --> J[ensureInteractiveLogin]
  J --> K{Stored session exists?}
  K -- No --> F
  K -- Yes --> L{Refresh token still valid?}
  L -- No --> F
  L -- Yes --> M[createClient and GET /api/auth/me]
  M --> N{Session still accepted?}
  N -- No --> F
  N -- Yes --> O[Interactive menu ready]

  E --> P[Start PKCE and callback server]
  F --> P
  P --> Q[Open browser to /api/cli/login]
  Q --> R[Wait for local callback with code and state]
  R --> S[POST /api/cli/token]
  S --> T[Store session.json]
  T --> O

  O --> U{Current directory contains SKILL.md?}
  U -- Yes --> V{Upload current directory now?}
  V -- Yes --> W[runInteractiveUpload]
  V -- No --> X[Choose action]
  U -- No --> X

  X --> Y{Install, Update or Upload?}
  Y -->|Install| Z[runInteractiveInstall]
  Y -->|Update| U0[updateInstalledSkills]
  Y -->|Upload| W

  Z --> Z1[GET /api/skills]
  Z1 --> Z2[Choose skill or resolve skillRef]
  Z2 --> Z3[GET skill detail]
  Z3 --> Z4[Choose version or use provided version]
  Z4 --> Z5[Choose project/global scope]
  Z5 --> Z6[Choose agents]
  Z6 --> Z7[GET version detail]
  Z7 --> Z8[POST download audit]
  Z8 --> Z9[Write files to install targets]
  Z9 --> Z10[Update installed.json]
  Z10 --> END[Done]

  U0 --> U1[Read installed.json for active baseUrl]
  U1 --> U2[GET skill detail for each installed target]
  U2 --> U3{Latest differs from installed version?}
  U3 -- No --> U4[Skip target]
  U3 -- Yes --> U5[GET latest version detail]
  U5 --> U6[POST download audit]
  U6 --> U7[Overwrite target files]
  U7 --> U8[Update installed.json]
  U4 --> END
  U8 --> END

  W --> W1[Load local skill context]
  W1 --> W2{uploaded.json has skillId for this directory?}

  W2 -- No --> W3[Prompt initial version]
  W3 --> W4[createSkillFromDirectory]
  W4 --> W5[POST create skill]
  W5 --> W6[GET created skill detail]
  W6 --> W7[Update uploaded.json]
  W7 --> END

  W2 -- Yes --> W8[GET existing skill detail]
  W8 --> W9{Local version differs from latest?}
  W9 -- Yes --> W10{Download latest first?}
  W10 -- Yes --> W11[GET latest version detail]
  W11 --> W12[POST download audit]
  W12 --> W13[Overwrite local files and update installed.json]
  W13 --> END

  W10 -- No --> W14[Prompt new version]
  W9 -- No --> W14
  W14 --> W15[publishSkillFromDirectory]
  W15 --> W16[POST publish version]
  W16 --> W17[GET updated skill detail]
  W17 --> W18[Update uploaded.json]
  W18 --> END

State Storage

Session storage paths:

• macOS/Linux: ~/.config/skillshare/session.json
• Windows: %APPDATA%\\skillshare\\session.json

Centralized TUI state:

• uploaded.json sits next to session.json and stores uploaded skill directories plus the registry skill/version they map to.
• installed.json sits next to session.json and stores installed target directories plus the installed skill/version for each target.
• New installs and uploads no longer need to create skillshare.metadata.json in the target directories.

Authentication

Bearer token precedence:

• --token <token> has the highest priority.
• SKILLSHARE_TOKEN is used when --token is not provided.
• Stored interactive session is used only when neither explicit token source is present.

Example non-interactive usage with a personal access token:

export SKILLSHARE_TOKEN="<personal-access-token>"
npx @quadient/skillshare whoami

Update recorded installs to the latest versions:

npx @quadient/skillshare update
npx @quadient/skillshare update "Prompt Lint" --dry-run
npx @quadient/skillshare update 12 --target ./installed

Package Distribution

The CLI is prepared for publishing as @quadient/skillshare.

Recommended invocation:

npx @quadient/skillshare
bunx @quadient/skillshare

Packaging checks:

bunx tsc --noEmit
npm run build
npm pack --dry-run

Publishing from the repo root:

bun run publish:tui:dry-run
bun run publish:tui
bun run publish:tui -- --otp 123456

The publish script builds tui/, validates the packed files with npm pack --dry-run, and only then runs npm publish.