typeui-cli

name	typeui-cli
description	Guide for agentic tools to use the typeui.sh CLI for generating, updating, listing, and pulling design system skill files.
license	MIT
metadata	{"author":"typeui.sh"}

typeui.sh CLI Operator Skill

Mission

Use typeui.sh to generate, update, list, and pull design-system skill files for agentic tooling in a project.

When To Use This Skill

• User asks to create or refresh design-system instructions for agents.
• User wants to pull an existing style by slug.
• User wants to browse available styles and select one interactively.
• User asks for preview-only runs before writing files.

Preconditions

• Run commands from the target project root.
• Node.js 18+ is available.
• If running from this repository source, build first:
  • npm install
  • npm run build

Command Reference

• npx typeui.sh generate
  • Run interactive prompts and create new managed skill content.
• npx typeui.sh update
  • Update existing managed sections in generated files.
• npx typeui.sh pull <slug>
  • Pull a specific registry skill and write it to selected provider paths.
• npx typeui.sh list
  • List available registry slugs, show preview links, and pull one selection.

Local Dev Invocation (This Repo)

• node dist/cli.js --help
• node dist/cli.js generate
• node dist/cli.js update
• node dist/cli.js list
• node dist/cli.js pull <slug>

Shared Flags

• -p, --providers <providers>
  • Comma-separated providers (example: cursor,codex).
• --dry-run
  • Preview file changes without writing.

Provider Behavior

• Universal target is always included: .agents/skills/design-system/SKILL.md.
• Selected providers add extra output targets (for example .cursor/..., .codex/...).

Registry Behavior

• Source of truth for list/pull data is:
  • https://github.com/bergside/awesome-design-skills
• Registry index used by CLI:
  • https://raw.githubusercontent.com/bergside/awesome-design-skills/main/skills/index.json
• pull <slug> flow:
  1. Validate slug format.
  2. Resolve skillPath from index.
  3. Fetch markdown from the raw GitHub path.
• list flow:
  • Reads the same index and shows preview links from:
  • https://www.typeui.sh/design-systems/<slug>

Recommended Agent Workflow

1. If user knows the style: run pull <slug> --dry-run first.
2. If user does not know the style: run list and select one.
3. Re-run without --dry-run when preview looks correct.
4. Report generated/updated file paths and whether each changed.

Troubleshooting

• Registry pull failed: not_found
  • Slug is not in registry index or markdown path is missing.
  • Run list and pick a valid slug.
• Slug must contain only lowercase letters, numbers, dashes, or underscores
  • Normalize slug format before retrying.
• No existing managed design system found during update
  • Run generate first to create managed blocks.