@archetypeai/ds-cli

CLI for the Archetype AI Design System. Scaffold new projects, add the design system to existing ones, and manage components and agent configurations.

Run directly with npx:

npx @archetypeai/ds-cli create my-app
npx @archetypeai/ds-cli --help       # full usage
npx @archetypeai/ds-cli --version    # print version

Commands

create → Scaffold a new project

npx @archetypeai/ds-cli create my-app

Sets up a TypeScript SvelteKit + Tailwind v4 project with design tokens, both design system packages, and a demo page. Step by step it:

1. Scaffolds a minimal TypeScript SvelteKit project (sv create --types ts) with the Tailwind v4 plugin
2. Patches svelte.config.js so Svelte 5 runes work in third-party packages
3. Installs the design system packages — @archetypeai/ds-lib-tokens, @archetypeai/ds-ui-svelte-console (stable base tier), @archetypeai/ds-ui-svelte-labs (experimental tier) — plus their peers, and pins layerchart to the exact prerelease the labs charts require
4. Initializes the shadcn-svelte config for the source-install (modify) workflow: components.json with a registries pointer at both registries, and src/lib/utils.ts re-exporting the console helpers (one cn in the tree)
5. Optionally copies local fonts to static/fonts/
6. Creates src/routes/layout.css with the order-critical design system stylesheet (tailwindcss → tokens theme → @source directives for both package dists)
7. Sets up linting and formatting (ESLint + Prettier with the Svelte and Tailwind plugins, plus lint/format scripts)
8. Installs the agent configuration incl. ds-manifest.json (--codeagent cursor|claude) - unless none
9. Writes a demo page (src/routes/+page.svelte) composing components from both packages

| Flag | Values | Default | |------|--------|---------| | --framework | svelte | prompt | | --pm | npm, pnpm, bun, yarn | prompt | | --fonts <path> | path to PP Neue Montreal fonts folder | prompt | | --no-fonts | skip font installation (use system fallback) | - | | --codeagent | cursor, claude, none | prompt | | --defaults | force non-interactive mode | - |

npx @archetypeai/ds-cli create my-app --pm pnpm --no-fonts --codeagent claude
npx @archetypeai/ds-cli create my-app --pm npm --fonts /path/to/fonts --codeagent claude

Non-interactive mode (no TTY or --defaults): project name, --pm, --fonts <path> or --no-fonts, and --codeagent must be specified. The CLI lists missing options and exits so agents can ask the user before proceeding.

init → Add DS to an existing project

cd my-existing-app
npx @archetypeai/ds-cli init

Run from a SvelteKit project root. Auto-detects your package manager from the lockfile, installs Tailwind CSS v4 if missing, installs the design system packages (tokens + console + labs + peers), writes the shadcn-svelte config, and prepends the DS stylesheet to your src/routes/layout.css (preserving existing styles - imports that are already present are not duplicated). Unlike create, no demo page is written.

| Flag | Values | Default | |------|--------|---------| | --pm | npm, pnpm, bun, yarn | auto-detect | | --fonts <path> | path to PP Neue Montreal fonts folder | prompt | | --no-fonts | skip font installation (use system fallback) | - | | --codeagent | cursor, claude, none | prompt | | --defaults | force non-interactive mode | - |

npx @archetypeai/ds-cli init --pm npm --no-fonts --codeagent claude
npx @archetypeai/ds-cli init --pm npm --fonts /path/to/fonts --codeagent claude

Non-interactive mode (no TTY or --defaults): --fonts <path> or --no-fonts and --codeagent must be specified (--pm is auto-detected from the lockfile when possible).

add → Add components, tokens, or agent config

add ds-ui-svelte

npx @archetypeai/ds-cli add ds-ui-svelte

Installs editable component source from the trimmed labs registry (the modify workflow — composing from the npm packages is the default and is what create/init set up). The CLI installs the base packages (@archetypeai/ds-lib-tokens, @archetypeai/ds-ui-svelte-console, tw-animate-css), sets up shadcn-svelte if needed (components.json, src/lib/utils.ts re-exporting the console helpers), then installs every component listed by the registry's /r/all.json endpoint — the shadcn-svelte CLI resolves each item's npm dependencies from the registry metadata, and the CLI re-pins layerchart to the exact prerelease afterwards. A freshly created components.json defaults to typescript: true; an existing components.json is never modified, so JS projects (typescript: false) keep working - the shadcn-svelte CLI strips types from the registry's TypeScript sources on install.

| Flag | Values | Default | |------|--------|---------| | --fonts <path> | path to PP Neue Montreal fonts folder | prompt | | --no-fonts | skip font installation (use system fallback) | - |

npx @archetypeai/ds-cli add ds-ui-svelte --fonts /path/to/fonts
npx @archetypeai/ds-cli add ds-ui-svelte --no-fonts

add ds-lib-tokens

npx @archetypeai/ds-cli add ds-lib-tokens

Installs @archetypeai/ds-lib-tokens (plus tailwindcss and tw-animate-css), prepends the imports to src/routes/layout.css, and optionally installs local fonts.

| Flag | Values | Default | |------|--------|---------| | --fonts <path> | path to PP Neue Montreal fonts folder | prompt | | --no-fonts | skip font installation (use system fallback) | - |

npx @archetypeai/ds-cli add ds-lib-tokens --fonts /path/to/fonts
npx @archetypeai/ds-cli add ds-lib-tokens --no-fonts

Non-interactive mode (no TTY or --defaults): font flags must be specified. The CLI lists missing options and exits so agents can ask the user before proceeding.

add ds-config-codeagent

npx @archetypeai/ds-cli add ds-config-codeagent --cursor
npx @archetypeai/ds-cli add ds-config-codeagent --claude

| Flag | Effect | |------|--------| | --cursor | Copies AGENTS.md + ds-manifest.json to the project root | | --claude | Copies CLAUDE.md + ds-manifest.json to the project root |

Without a flag, an interactive prompt asks which IDE to configure (in non-interactive mode the flag is required). Files that already exist are skipped, so re-running is safe.

The configuration is two files: the instruction file (CLAUDE.md/AGENTS.md — stack, CSS wiring, tokens, typography, patterns, hard rules) and ds-manifest.json — a machine-readable catalog of every component (import subpath, registry source URL, description, usage recipes grounded in real product usage, and variant axes with defaults). The manifest is generated from the component source and each primitive's colocated usage.json.

Fonts

The --fonts <path> flag expects a local folder containing all 15 PP Neue Montreal files (9 Sans .ttf + 6 Mono .otf). The CLI validates the folder and copies the files to static/fonts/, where the @font-face declarations in @archetypeai/ds-lib-tokens/fonts.css expect them. With --no-fonts, the theme falls back to system fonts.

Registries

Editable component source is served by two registries: labs at https://design-system-labs.archetypeai.workers.dev (override with REGISTRY_URL) and console at https://design-system-console.archetypeai.workers.dev (override with CONSOLE_REGISTRY_URL). ds add ds-ui-svelte bulk-installs from the labs registry; individual components from either tier install with npx shadcn-svelte@latest add <registry>/r/<name>.json. The CLI validates every component URL (HTTPS, /r/<name>.json pattern) before passing it to shadcn-svelte add.