### Get Started - Basic Usage

Source: https://github.com/royfw/start-ts-by/blob/main/docs/README.md

Basic commands to start a new project using npx.

```bash
npx start-ts-by [projectName]
# or
npx start-ts-by create [projectName]
```

--------------------------------

### Template Source Syntax Examples

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/001_add-monorepo-flag/_kilocode/20250912-TASK-START_TS_BY_001-gpt5-分析專案、增加支援 `--no-interaction`/分析與設計-`--no-interaction`與非JSON輸入-結論.md

Examples of specifying template sources using GitHub format, custom Git URLs, and local directories.

```bash
# GitHub standard format
npx start-ts-by my-app --ni -t user/repo
npx start-ts-by my-app --ni -t user/repo#branch
npx start-ts-by my-app --ni -t user/repo#branch/subdir

# Custom Git source
npx start-ts-by my-app --ni -t git@gitlab.com:group/repo.git#dev/templates

# Local directory
npx start-ts-by my-app --ni -t ./my-template
npx start-ts-by my-app --ni -t ./templates/basic-app
```

--------------------------------

### Example Output for Listing Templates

Source: https://github.com/royfw/start-ts-by/blob/main/docs/README.md

Example output when listing available templates.

```bash
📦 Available Templates:

📌 Built-in Templates (builtin)
  ├─ TypeScript Library
  ├─ TypeScript Application
  └─ Monorepo Template

🌐 start-ts-templates (registry)
  ├─ App (tsdown)
  └─ Library

✨ Total 5 templates from 2 sources

```

--------------------------------

### Custom Cache Configuration Example

Source: https://github.com/royfw/start-ts-by/blob/main/docs/registry.md

Example of customizing cache directory and time-to-live in registry configuration.

```json
{
  "registries": [...],
  "cacheDir": ".my-custom-cache",
  "cacheTTL": 7200000
}
```

--------------------------------

### Registry Configuration File Example

Source: https://github.com/royfw/start-ts-by/blob/main/docs/registry.md

Example of a registry-config.json file to load template definitions from external sources.

```json
{
  "registries": [
    {
      "name": "start-ts-templates",
      "url": "https://raw.githubusercontent.com/royfw/start-ts-templates/main/registry.json",
      "enabled": true
    }
  ],
  "cacheDir": ".cache/registries",
  "cacheTTL": 3600000
}
```

--------------------------------

### List Command Output Example

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/002_registry-json-support/_kilocode/20251216-TASK-START_TS_BY_003-registry-json-support/implementation-summary.md

An example of the output from the `npx start-ts-by --list` command, showing available built-in and registry templates.

```bash
# View all available templates
npx start-ts-by --list

# Output example:
# 📦 Available Templates:
# 
# 📌 Built-in Templates (builtin)
#   ├─ TypeScript Library
#   └─ TypeScript Application
# 
# 🌐 start-ts-templates (registry)

```

--------------------------------

### Install commitlint and Commitizen dependencies

Source: https://github.com/royfw/start-ts-by/blob/main/docs/development.md

Commands to install necessary packages for commitlint and Commitizen.

```sh
pnpm add -D cz-conventional-changelog @commitlint/cz-commitlint @commitlint/config-conventional @commitlint/cli commitizen
```

--------------------------------

### Basic .stb.vars File Format

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/001_add-monorepo-flag/_kilocode/20250912-TASK-START_TS_BY_001-gpt5-分析專案、增加支援 `--no-interaction`/分析與設計-`--no-interaction`與非JSON輸入-結論.md

An example of a .stb.vars file demonstrating basic settings, file removal configurations, execution commands, and nested structures.

```ini
# Project basic settings
name=my-awesome-app
template=royfw/starter-ts-app

# Remove file settings
removeList[0].field=README.md
removeList[0].isRemove=true
removeList[1].field=.github
removeList[1].isRemove=false

# Execute command settings
execList[0].key=gitInit
execList[0].isExec=true
execList[1].key=npmInstall
execList[1].isExec=true

# Nested settings
project.version=1.0.0
project.description=My awesome TypeScript project
```

--------------------------------

### Verify pnpm version and install dependencies

Source: https://github.com/royfw/start-ts-by/blob/main/docs/development.md

Commands to check the installed pnpm version and install project dependencies using pnpm.

```sh
pnpm -v # 10.0.0
pnpm install --frozen-lockfile
```

--------------------------------

### Registry Configuration

Source: https://github.com/royfw/start-ts-by/blob/main/docs/README.md

Example JSON configuration for setting up external registries.

```json
{
  "registries": [
    {
      "name": "start-ts-templates",
      "url": "https://raw.githubusercontent.com/royfw/start-ts-templates/main/registry.json",
      "enabled": true
    }
  ],
  "cacheDir": ".cache/registries",
  "cacheTTL": 3600000
}

```

--------------------------------

### Install pnpm

Source: https://github.com/royfw/start-ts-by/blob/main/docs/development.md

Commands to install and activate a specific version of pnpm using corepack.

```sh
corepack enable pnpm

corepack prepare pnpm@10.0.0 --activate
corepack use pnpm@10.0.0

# clean local corepack cache
corepack cache clean


# Cannot find matching keyid: {"signatures":[{"sig":"MEQCIGfJsZcWOYet7N9s+gixdrVR7NuxXRagWTDp3...
# use
npm install --global corepack@latest
```

--------------------------------

### Interactive Usage Example

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/002_registry-json-support/_kilocode/20251216-TASK-START_TS_BY_003-registry-json-support/implementation-summary.md

Demonstrates the interactive workflow when creating a new project using start-ts-by, including template selection.

```bash
npx start-ts-by create my-project
# 1. Select source (built-in/Registry/manual)
# 2. Select template
# 3. Confirm options
```

--------------------------------

### Variable File Format (.vars)

Source: https://github.com/royfw/start-ts-by/blob/main/docs/README.md

Example of a .vars file with key=value pairs and nested variables.

```bash
# project.vars
name=my-awesome-app
template=user/repo

# Nested variables for removeList
removeList[0].field=README.md
removeList[0].isRemove=true
removeList[1].field=.github
removeList[1].isRemove=false

# Execution options
execList[0].key=gitInit
execList[0].command=git init
execList[0].isExec=true

# File content (@ prefix reads from file)
# token=@./secret-token.txt

# Include other vars files
# include: ./common.vars

```

--------------------------------

### Syntax Highlighting Example

Source: https://github.com/royfw/start-ts-by/blob/main/docs/markdown-examples.md

Demonstrates syntax highlighting with line highlighting using Shiki.

```markdown
```js{4}
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
```
```

--------------------------------

### List Command Usage

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/002_registry-json-support/_kilocode/20251216-TASK-START_TS_BY_003-registry-json-support/implementation-summary.md

Examples of how to use the `--list` command with different options for viewing available templates.

```bash
# General mode
npx start-ts-by --list

# JSON format (for programmatic use)
npx start-ts-by --list-json

# Verbose mode (includes descriptions)
npx start-ts-by --list-verbose
```

--------------------------------

### List Command Output Example

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/002_registry-json-support/_kilocode/20251216-TASK-START_TS_BY_003-registry-json-support/technical-design.md

Example output of the 'npx start-ts-by list' command, showing available templates categorized by source.

```bash
$ npx start-ts-by list

📋 Available Templates:

[Built-in]
  • royfw/starter-ts-app              Starter TypeScript App
  • royfw/starter-ts-lib              Starter TypeScript Library
  • royfw/starter-ts-lib-rolldown     Starter TypeScript Library - rolldown
  • royfw/starter-turbo               Starter TypeScript TurboRepo

[Official Templates] (royfw/start-ts-templates)
  • app-tsdown                           App (tsdown)
  • lib                                  Library
  • monorepo                             Monorepo (Turborepo)
  • express-api                          Express API Server

[Community Templates] (community/templates)
  • react-vite                           React + Vite Starter
  • nextjs-app                           Next.js App Router
  • fastify-api                          Fastify API Template

Total: 11 templates available

💡 Usage:
  Interactive:      npx start-ts-by
  Non-interactive:  npx start-ts-by my-app --ni --template <repo>
  Registry:         npx start-ts-by my-app --ni --template registry:app-tsdown
```

--------------------------------

### Custom Containers Example

Source: https://github.com/royfw/start-ts-by/blob/main/docs/markdown-examples.md

Shows examples of various custom container types like info, tip, warning, danger, and details.

```markdown
::: info
This is an info box.
:::

::: tip
This is a tip.
:::

::: warning
This is a warning.
:::

::: danger
This is a dangerous warning.
:::

::: details
This is a details block.
:::
```

--------------------------------

### useData() API Example

Source: https://github.com/royfw/start-ts-by/blob/main/docs/api-examples.md

Demonstrates how to use the useData() API to access site, theme, and page data in a .md file.

```markdown
<script setup>
import { useData } from 'vitepress'

const { theme, page, frontmatter } = useData()
</script>

## Results

### Theme Data
<pre>{{ theme }}</pre>

### Page Data
<pre>{{ page }}</pre>

### Page Frontmatter
<pre>{{ frontmatter }}</pre>
```

--------------------------------

### Multi-Capability Example: Auth Spec

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/AGENTS.md

Content of the spec.md file for the 'auth' capability in the multi-capability example.

```markdown
## ADDED Requirements
### Requirement: Two-Factor Authentication
...
```

--------------------------------

### Advanced Variable Settings with --vars

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/001_add-monorepo-flag/_kilocode/20250912-TASK-START_TS_BY_001-gpt5-分析專案、增加支援 `--no-interaction`/分析與設計-`--no-interaction`與非JSON輸入-結論.md

Demonstrates setting basic parameters, file removal lists, execution lists, and using --vars-file for configuration.

```bash
# Setting basic parameters
npx start-ts-by my-app -t user/repo --ni --vars name=my-app,template=user/repo

# Setting file removal list
npx start-ts-by my-app -t user/repo --ni \
  --vars "removeList[0].field=README.md,removeList[0].isRemove=true" \
  --vars "removeList[1].field=.github,removeList[1].isRemove=false"

# Setting execution list
npx start-ts-by my-app -t user/repo --ni \
  --vars "execList[0].key=gitInit,execList[0].isExec=true" \
  --vars "execList[1].key=npmInstall,execList[1].isExec=false"

# Using a file for settings
npx start-ts-by my-app -t user/repo --ni --vars-file ./.stb.vars

# Mixed usage (CLI takes precedence)
npx start-ts-by my-app -t user/repo --ni --vars-file ./.stb.vars --vars name=override-name
```

--------------------------------

### File Content Reference with --vars

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/001_add-monorepo-flag/_kilocode/20250912-TASK-START_TS_BY_001-gpt5-分析專案、增加支援 `--no-interaction`/分析與設計-`--no-interaction`與非JSON輸入-結論.md

Examples of referencing file content directly within the --vars parameter using the '@' prefix.

```bash
--vars token=@./secrets/api-token.txt
--vars config=@./config.json
```

--------------------------------

### List Available Templates Commands

Source: https://github.com/royfw/start-ts-by/blob/main/docs/registry.md

Command-line interface commands to list available templates from registries.

```bash
# View all available templates
npx start-ts-by --list

# JSON format output
npx start-ts-by --list-json

# Include detailed descriptions
npx start-ts-by --list-verbose
```

--------------------------------

### Multi-Capability Example: Notifications Spec

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/AGENTS.md

Content of the spec.md file for the 'notifications' capability in the multi-capability example.

```markdown
## ADDED Requirements
### Requirement: OTP Email Notification
...
```

--------------------------------

### Multi-Capability Example Directory Structure

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/AGENTS.md

Illustrates the directory structure for a change involving multiple capabilities, specifically adding two-factor authentication and OTP email notification.

```text
openspec/changes/add-2fa-notify/
├── proposal.md
├── tasks.md
└── specs/
    ├── auth/
    │   └── spec.md   # ADDED: Two-Factor Authentication
    └── notifications/
        └── spec.md   # ADDED: OTP email notification
```

--------------------------------

### Graceful Degradation for Registry Loading

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/002_registry-json-support/_kilocode/20251216-TASK-START_TS_BY_003-registry-json-support/implementation-summary.md

Example of how to handle registry loading failures gracefully, falling back to built-in templates.

```typescript
// Graceful degradation
try {
  const registries = await loadRegistries();
} catch (error) {
  console.warn('⚠️ Registry loading failed, using built-in templates');
  // Continue using built-in templates
}
```

--------------------------------

### Example for RENAMED requirement

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/AGENTS.md

Demonstrates the format for specifying renamed requirements, including the 'FROM' and 'TO' sections.

```markdown
## RENAMED Requirements
- FROM: `### Requirement: Login`
- TO: `### Requirement: User Authentication`
```

--------------------------------

### Variable File Format (.vars)

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/001_add-monorepo-flag/_kilocode/20250912-TASK-START_TS_BY_001-gpt5-分析專案、增加支援 `--no-interaction`/實作-CLI非互動與變數輸入-結論.md

An example demonstrating the format and capabilities of a .vars file, including basic variables, nested structures, execution options, file content inclusion, and file inclusion directives.

```bash
# Basic variables
name=my-awesome-app
template=user/repo

# Nested structure
removeList[0].field=README.md
removeList[0].isRemove=true

# Execution options
execList[0].key=gitInit
execList[0].isExec=true

# File content
# token=@./secret.txt

# Include other files
# include: ./common.vars
```

--------------------------------

### Registry Config Format Example

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/002_registry-json-support/_kilocode/20251216-TASK-START_TS_BY_003-registry-json-support/technical-design.md

An example of the registry-config.json file, showing how to configure multiple registries with their sources, enabled status, and priority.

```json
{
  "version": "1.0.0",
  "registries": [
    {
      "name": "Official Templates",
      "source": "royfw/start-ts-templates",
      "enabled": true,
      "priority": 10
    },
    {
      "name": "Community Templates",
      "source": "https://github.com/community/templates.git",
      "enabled": true,
      "priority": 20
    },
    {
      "name": "Local Templates",
      "source": "./local-templates",
      "enabled": true,
      "priority": 30
    }
  ]
}

```

--------------------------------

### Proposal Structure - tasks.md

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/AGENTS.md

An example of the `tasks.md` file structure, used for outlining implementation steps and checklists.

```markdown
## 1. Implementation
- [ ] 1.1 Create database schema
- [ ] 1.2 Implement API endpoint
- [ ] 1.3 Add frontend component
- [ ] 1.4 Write tests
```

--------------------------------

### Get CLI Help Output

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/001_add-monorepo-flag/_kilocode/20250912-TASK-START_TS_BY_001-gpt5-分析專案、增加支援 `--no-interaction`/驗證 CLI help 與 README_docs 一致性-過程.md

Commands to retrieve the help output for the main command and the 'create' subcommand.

```bash
npx tsx src/index.ts --help
npx tsx src/index.ts create --help
```

--------------------------------

### Git commit with Commitizen

Source: https://github.com/royfw/start-ts-by/blob/main/docs/development.md

Command to initiate a Git commit using Commitizen for guided commit message creation.

```sh
# 輸入 git commit 出現 commitizen 選項
git commit

? Select the type of change that you're committing: (Use arrow keys)
  feat:     A new feature 
  fix:      A bug fix 
  docs:     Documentation only changes 
  style:    Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons,
 etc) 
  refactor: A code change that neither fixes a bug nor adds a feature 
  perf:     A code change that improves performance 


```

--------------------------------

### Interactive Project Creation Flow

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/002_registry-json-support/_kilocode/20251216-TASK-START_TS_BY_003-registry-json-support/technical-design.md

Example of an interactive project creation process using the start-ts-by CLI, including template selection and configuration prompts.

```bash
$ npx start-ts-by

🚀 Creating project...
✔ Enter project name: my-awesome-app

? Select template source: (Use arrow keys)
❯ Built-in Templates
  Official Templates (royfw/start-ts-templates)
  Community Templates
  Enter custom GitHub URL

# 使用者選擇 "Official Templates"

? Select a template: (Use arrow keys)
❯ app-tsdown - App (tsdown)
  lib - Library
  monorepo - Monorepo (Turborepo)
  express-api - Express API Server

# 使用者選擇 "app-tsdown"

? Keep husky? (Y/n) y
? Keep GitHub Actions? (y/N) n
? Enable monorepo mode? (y/N) n
? Initialize git? (Y/n) y
? Install dependencies? (Y/n) y

📦 Cloning template...
🗑️  Removing unwanted files...
📝 Initializing package.json...
🔧 Running git init...
📦 Installing dependencies...

✅ Project "my-awesome-app" has been created at ./my-awesome-app
🎉 Start building your project!
```

--------------------------------

### TypeScript Strict Mode Solutions

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/002_registry-json-support/_kilocode/20251216-TASK-START_TS_BY_003-registry-json-support/implementation-summary.md

Examples of how to handle type mismatches in mock functions or unused parameters when using TypeScript's strict mode.

```typescript
// Use appropriate type assertion
const mockFunction = vi.fn() as any;

// Or use explicit parameter naming
function loadRegistry(_url: string): Promise<RegistryJson> {
  // Use _ prefix to mark unused parameters
}
```

--------------------------------

### --vars Parameter Basic Syntax

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/001_add-monorepo-flag/_kilocode/20250912-TASK-START_TS_BY_001-gpt5-分析專案、增加支援 `--no-interaction`/分析與設計-`--no-interaction`與非JSON輸入-結論.md

Illustrates the basic syntax for the --vars parameter, including single key-value pairs, comma-separated pairs, and keys with spaces.

```bash
--vars key=value
--vars key1=value1,key2=value2
--vars "complex key=value with spaces"
```

--------------------------------

### Advanced Variable Input

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/001_add-monorepo-flag/_kilocode/20250912-TASK-START_TS_BY_001-gpt5-分析專案、增加支援 `--no-interaction`/實作-CLI非互動與變數輸入-結論.md

Examples showcasing advanced variable input methods, including inline variables, using variable files, and combining both.

```bash
# Inline variables
npx start-ts-by my-app --ni --vars name=my-app,template=user/repo

# Variable file
npx start-ts-by my-app --ni --vars-file ./project.vars

# Combination
npx start-ts-by my-app --ni --vars-file ./base.vars --vars template=custom/repo
```

--------------------------------

### Advanced File Features in .stb.vars

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/001_add-monorepo-flag/_kilocode/20250912-TASK-START_TS_BY_001-gpt5-分析專案、增加支援 `--no-interaction`/分析與設計-`--no-interaction`與非JSON輸入-結論.md

Illustrates advanced features in .stb.vars files, including comments, file inclusion, multi-line values, and referencing file content.

```ini
# Supports comments
# This is a comment line

# Supports including other files
include=./base-config.vars
include=./environment/dev.vars

# Supports multi-line values (using backslash for continuation)
description=This is a long description \
that spans multiple lines

# Supports referencing file content
api_key=@./secrets/api.key
certificate=@./certs/ssl.pem
```

--------------------------------

### Basic Non-Interactive Mode

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/001_add-monorepo-flag/_kilocode/20250912-TASK-START_TS_BY_001-gpt5-分析專案、增加支援 `--no-interaction`/實作-CLI非互動與變數輸入-結論.md

Examples demonstrating how to use the --no-interaction flag (or its shorthand --ni) for basic project creation without interactive prompts.

```bash
npx start-ts-by my-app -t user/repo --no-interaction
npx start-ts-by my-app -t user/repo --ni
```

--------------------------------

### --vars Parameter Nested Object Syntax

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/001_add-monorepo-flag/_kilocode/20250912-TASK-START_TS_BY_001-gpt5-分析專案、增加支援 `--no-interaction`/分析與設計-`--no-interaction`與非JSON輸入-結論.md

Shows how to use dot notation with the --vars parameter to define nested object structures.

```bash
--vars project.name=my-app
--vars project.config.debug=true
--vars settings.database.host=localhost
```

--------------------------------

### Disable Specific Registry Example

Source: https://github.com/royfw/start-ts-by/blob/main/docs/registry.md

Example of disabling a registry by setting its 'enabled' field to false.

```json
{
  "registries": [
    {
      "name": "primary-registry",
      "url": "https://example.com/registry.json",
      "enabled": true
    },
    {
      "name": "backup-registry",
      "url": "https://backup.example.com/registry.json",
      "enabled": false
    }
  ]
}
```

--------------------------------

### List Available Templates

Source: https://github.com/royfw/start-ts-by/blob/main/docs/README.md

Commands to list available templates in different formats.

```bash
# List all available templates (human-readable format)
npx start-ts-by --list
npx start-ts-by -l

# List templates in JSON format (for programmatic use)
npx start-ts-by --list-json

# List templates with descriptions (verbose mode)
npx start-ts-by --list-verbose

```

--------------------------------

### Basic Non-Interactive Usage

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/001_add-monorepo-flag/_kilocode/20250912-TASK-START_TS_BY_001-gpt5-分析專案、增加支援 `--no-interaction`/分析與設計-`--no-interaction`與非JSON輸入-結論.md

Examples of using the --no-interaction flag with different aliases and combined with the --yes flag.

```bash
npx start-ts-by my-app -t royfw/starter-ts-app --no-interaction

# Using the alias
npx start-ts-by my-app -t royfw/starter-ts-app --ni

# Combined with automatic confirmation
npx start-ts-by my-app -t royfw/starter-ts-app --ni --yes
```

--------------------------------

### CLI Help

Source: https://github.com/royfw/start-ts-by/blob/main/docs/README.md

Displays the help information for the start-ts-by CLI, including available options and commands.

```sh
npx start-ts-by --help

Usage: start-ts-by [options] [command]

Start TypeScript project by git repo or local folder templates

Options:
  -V, --version                     output the version number
  -l, --list                        List all available templates
  --list-json                       List all available templates in JSON format
  --list-verbose                    List all available templates with descriptions
  -h, --help                        display help for command

Commands:
  create [options] [name]           Create new project from template (Default)
  help [command]                    Display help for command

# Create command options:
npx start-ts-by create --help

Options:
  -t, --template <repo>             Template source (user/repo, git@domain:group/repo.git, ./local-folder)
  --skip-prompt                     Skip prompt (deprecated, use --no-interaction)
  --no-interaction, --ni            Non-interactive mode, skip all prompts
  --yes, -y                         Use defaults and skip confirmations when applicable
  --vars <pairs...>                 Variables in key=value format (can be used multiple times)
  --vars-file <path>                Path to variables file (non-JSON, supports includes)
  --strict                          Strict mode: treat duplicate keys and type conflicts as errors
  --rm <files...>                   Remove files/folders after project creation
  --no-husky                        Remove .husky
  --github                          Keep .github/workflows
  --gitlab                          Keep .gitlab-ci.yml and GitLab CI/CD config
  --deploy                          Keep deploy/.deploy configuration
  --git-init                        Run git init after creation
  --npm-install                     Run npm install after creation
  --monorepo                        Remove monorepo conflicting files (lock files, workspace config, .npmrc, .husky, .github, prepare script, packageManager field)
  -h, --help                        display help for command
```

--------------------------------

### CLI Help

Source: https://github.com/royfw/start-ts-by/blob/main/README.md

Displays the help information for the start-ts-by CLI, including available options and commands.

```sh
npx start-ts-by --help

Usage: start-ts-by [options] [command]

Start TypeScript project by git repo or local folder templates

Options:
  -V, --version                     output the version number
  -l, --list                        List all available templates
  --list-json                       List all available templates in JSON format
  --list-verbose                    List all available templates with descriptions
  -h, --help                        display help for command

Commands:
  create [options] [name]  Create a new project from a git template (Default)
  help [command]           display help for command

# Create command options:
npx start-ts-by create --help

Options:
  -t, --template <repo>             Template source (user/repo, git@domain:group/repo.git, ./local-folder)
  --skip-prompt                     Skip prompt (deprecated, use --no-interaction)
  --no-interaction, --ni            Non-interactive mode, skip all prompts
  --yes, -y                         Use defaults and skip confirmations when applicable
  --vars <pairs...>                 Variables in key=value format, supports nested keys and arrays (can be used multiple times) (default: [])
  --vars-file <path>                Path to variables file (non-JSON, supports includes)
  --strict                          Strict mode: treat duplicate keys and type conflicts as errors
  --rm <files...>                   Remove files/folders after project creation
  --no-husky                        Remove .husky
  --github                          Keep .github/workflows
  --gitlab                          Keep .gitlab-ci.yml and GitLab CI/CD config
  --deploy                          Keep deploy/.deploy configuration
  --git-init                        Run git init after creation
  --npm-install                     Run npm install after creation
  --monorepo                        Remove monorepo conflicting files (lock files, workspace config, .npmrc, .husky, .github, prepare script, packageManager field)
  -h, --help                        display help for command
```

--------------------------------

### Interactive Mode

Source: https://github.com/royfw/start-ts-by/blob/main/docs/README.md

Initiates interactive mode for project creation, prompting for project name and template.

```bash
npx start-ts-by
# Example workflow:
# 🚀 Start creating project...
# ✔ Enter project name: my-app
# ✔ Enter template (e.g. user/repo, ./local-path, git@domain:group/repo.git)
# ? Choose a template (Use arrow keys)
#   royfw/starter-ts-app (Starter TypeScript App)
#   royfw/starter-ts-lib (Starter TypeScript Library)
#   ...

```

--------------------------------

### Registry.json Format Example

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/002_registry-json-support/_kilocode/20251216-TASK-START_TS_BY_003-registry-json-support/technical-design.md

An example of the registry.json file structure, detailing repository information and a list of available templates.

```json
{
  "repo": "royfw/start-ts-templates",
  "defaultRef": "main",
  "name": "Official Start-TS Templates",
  "description": "Official template collection for start-ts-by",
  "templates": [
    {
      "id": "app-tsdown",
      "path": "templates/app-tsdown",
      "title": "App (tsdown)",
      "description": "TypeScript application with tsdown bundler",
      "tags": ["app", "tsdown", "typescript"]
    },
    {
      "id": "lib",
      "path": "templates/lib",
      "title": "Library",
      "description": "TypeScript library starter",
      "tags": ["library", "typescript"]
    },
    {
      "id": "monorepo",
      "path": "templates/monorepo",
      "title": "Monorepo (Turborepo)",
      "description": "Monorepo setup with Turborepo",
      "tags": ["monorepo", "turborepo"]
    }
  ]
}

```

--------------------------------

### Template Sources with Branches/Subdirectories

Source: https://github.com/royfw/start-ts-by/blob/main/docs/README.md

Specifying template sources with branches or subdirectories.

```bash
npx start-ts-by my-app -t royfw/starter-ts-app#dev/subdir --ni
npx start-ts-by my-app -t git@your.gitlab:group/repo.git#v2/templates --ni
npx start-ts-by my-app -t ./my-template-folder/subdir --ni

```

--------------------------------

### Registry.json Format

Source: https://github.com/royfw/start-ts-by/blob/main/docs/registry.md

The structure for a registry.json file, defining templates and repository information.

```json
{
  "repo": "your-org/your-templates-repo",
  "defaultRef": "main",
  "version": "1.0.0",
  "name": "My Templates",
  "description": "A collection of TypeScript templates",
  "templates": [
    {
      "id": "unique-template-id",
      "path": "templates/template-directory",
      "title": "Human-readable Template Name",
      "description": "Optional template description"
    }
  ]
}
```

--------------------------------

### Registry.json Format

Source: https://github.com/royfw/start-ts-by/blob/main/docs/README.md

Defines the expected JSON format for external registry configuration files.

```json
{
  "repo": "your-org/your-templates-repo",
  "defaultRef": "main",
  "templates": [
    {
      "id": "template-id",
      "path": "templates/template-path",
      "title": "Template Display Name",
      "description": "Optional description"
    }
  ]
}
```

--------------------------------

### Advanced Non-interactive with Variables

Source: https://github.com/royfw/start-ts-by/blob/main/docs/README.md

Using --vars and --vars-file for inline variables and configuration files.

```bash
# Using --vars for inline variables
npx start-ts-by my-app --ni --vars name=my-app,template=user/repo
npx start-ts-by my-app --ni --vars "removeList[0].field=README.md,removeList[0].isRemove=true"

# Using --vars-file for configuration files
npx start-ts-by my-app --ni --vars-file ./project.vars

# Combining multiple sources (vars override vars-file)
npx start-ts-by my-app --ni --vars-file ./base.vars --vars template=user/custom-repo

```

--------------------------------

### Registry Management Commands

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/002_registry-json-support/_kilocode/20251216-TASK-START_TS_BY_003-registry-json-support/implementation-summary.md

Commands to manage registries, including adding, listing, and updating them.

```bash
npx start-ts-by registry add <url>
npx start-ts-by registry list
npx start-ts-by registry update
```

--------------------------------

### Main Command Help Output

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/001_add-monorepo-flag/_kilocode/20250912-TASK-START_TS_BY_001-gpt5-分析專案、增加支援 `--no-interaction`/驗證 CLI help 與 README_docs 一致性-過程.md

The help output for the main 'start-ts-by' command.

```bash
Usage: start-ts-by [options] [command]

Start TypeScript project by git repo templates

Options:
  -V, --version            output the version number
  -h, --help               display help for command

Commands:
  create [options] [name]  Create a new project from a git template (Default)
  help [command]           display help for command
```

--------------------------------

### Husky initialization

Source: https://github.com/royfw/start-ts-by/blob/main/docs/development.md

Commands to add Husky as a dev dependency and initialize it in the project.

```sh
pnpm add -wD husky

pnpm exec husky init
```

--------------------------------

### Non-interactive Mode - Monorepo

Source: https://github.com/royfw/start-ts-by/blob/main/docs/README.md

Creating a project in monorepo mode using the --monorepo flag.

```bash
# Non-interactive mode: Remove lock files, workspace config, .npmrc, and packageManager field
npx start-ts-by my-app -t user/repo --monorepo --ni

# Combine with other flags
npx start-ts-by my-app -t user/repo --monorepo --no-husky --ni

# Interactive mode: Specify --monorepo flag upfront
npx start-ts-by my-app -t user/repo --monorepo

# Interactive mode: Will prompt for monorepo mode if not specified
npx start-ts-by my-app -t user/repo
# During prompts, you'll see:
# ? Enable monorepo mode? (Remove lock files, workspace config, .npmrc, and packageManager field) (y/N)

```

--------------------------------

### Create Subcommand Help Output

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/001_add-monorepo-flag/_kilocode/20250912-TASK-START_TS_BY_001-gpt5-分析專案、增加支援 `--no-interaction`/驗證 CLI help 與 README_docs 一致性-過程.md

The help output for the 'create' subcommand.

```bash
Usage: start-ts-by create [options] [name]

Create a new project from a git template (Default)

Options:
  -t, --template <repo>   Template source, e.g. user/repo,
                          git@domain:group/repo.git, ./local-folder
  --skip-prompt           Skip prompt (deprecated, use --no-interaction)
                          (default: false)
  --no-interaction, --ni  Non-interactive mode, skip all prompts (default:
                          false)
  --yes, -y               Use defaults and skip confirmations when applicable
                          (default: false)
  --vars <pairs...>       Variables in key=value format, supports nested keys
                          and arrays (can be used multiple times) (default: [])
  --vars-file <path>      Path to variables file (non-JSON, supports includes)
  --strict                Strict mode: treat duplicate keys and type conflicts
                          as errors (default: false)
  --rm <files...>         Remove files/folders after project creation (default: [])
  --no-husky              Remove .husky
  --github                Keep .github/workflows (default: false)
  --git-init              Run git init after creation (default: false)
  --npm-install           Run npm install after creation (default: false)
  -h, --help              display help for command
```

--------------------------------

### Proposal Structure - spec deltas

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/AGENTS.md

Example of how to structure spec deltas within the `changes/[change-id]/specs/[capability]/spec.md` file, covering added, modified, and removed requirements.

```markdown
## ADDED Requirements
### Requirement: New Feature
The system SHALL provide...

#### Scenario: Success case
- **WHEN** user performs action
- **THEN** expected result

## MODIFIED Requirements
### Requirement: Existing Feature
[Complete modified requirement]

## REMOVED Requirements
### Requirement: Old Feature
**Reason**: [Why removing]
**Migration**: [How to handle]
```

--------------------------------

### Interactive Mode - Monorepo Mode

Source: https://github.com/royfw/start-ts-by/blob/main/README.md

Specifying monorepo mode during interactive project creation.

```bash
# Interactive mode: Specify --monorepo flag upfront
npx start-ts-by my-app -t user/repo --monorepo

# Interactive mode: Will prompt for monorepo mode if not specified
npx start-ts-by my-app -t user/repo
# During prompts, you'll see:
# ? Enable monorepo mode? (Remove lock files, workspace config, .npmrc, and packageManager field) (y/N)

```

--------------------------------

### Decision Tree for Creating Change Proposals

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/AGENTS.md

A decision tree to guide the process of creating change proposals, helping to determine whether to fix directly or create a new proposal.

```markdown
New request?
├─ Bug fix restoring spec behavior? → Fix directly
├─ Typo/format/comment? → Fix directly  
├─ New feature/capability? → Create proposal
├─ Breaking change? → Create proposal
├─ Architecture change? → Create proposal
└─ Unclear? → Create proposal (safer)
```

--------------------------------

### Local use by npx

Source: https://github.com/royfw/start-ts-by/blob/main/docs/development.md

Command to run the start-ts-by tool locally using npx.

```sh
npx start-ts-by
```

--------------------------------

### Non-interactive Mode - Monorepo Mode

Source: https://github.com/royfw/start-ts-by/blob/main/README.md

Creating a project in monorepo mode without interaction.

```bash
# Non-interactive mode: Remove lock files, workspace config, .npmrc, and packageManager field
npx start-ts-by my-app -t user/repo --monorepo --ni

# Combine with other flags
npx start-ts-by my-app -t user/repo --monorepo --no-husky --ni

```

--------------------------------

### --vars Parameter Array Index Syntax

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/001_add-monorepo-flag/_kilocode/20250912-TASK-START_TS_BY_001-gpt5-分析專案、增加支援 `--no-interaction`/分析與設計-`--no-interaction`與非JSON輸入-結論.md

Demonstrates using array indices with the --vars parameter to configure array elements, such as for file removal lists.

```bash
--vars removeList[0].field=README.md
--vars removeList[0].isRemove=true
--vars removeList[1].field=.husky
--vars removeList[1].isRemove=false
```

--------------------------------

### Registry Loading and Resolution

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/002_registry-json-support/_kilocode/20251216-TASK-START_TS_BY_003-registry-json-support/implementation-summary.md

Code snippet demonstrating how to load, validate, and resolve registry JSON data.

```typescript
// Load from URL or local file
const registry = await loadRegistryFromUrl(url);

// Format validation
validateRegistryJson(registry);

// Parse into a unified format
const resolved = resolveRegistry(registry, source);
```

--------------------------------

### Hierarchical Template Selection

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/002_registry-json-support/_kilocode/20251216-TASK-START_TS_BY_003-registry-json-support/implementation-summary.md

Illustrates the two-step process for selecting a template: first choosing a source, then choosing a template from that source.

```typescript
// First level: select source
const source = await selectSource(sources);

// Second level: select template
const template = await selectTemplate(source.templates);

// Construct the full path
const fullPath = buildTemplatePath(template);
```

--------------------------------

### Core Parameter Mapping

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/001_add-monorepo-flag/_kilocode/20250912-TASK-START_TS_BY_001-gpt5-分析專案、增加支援 `--no-interaction`/分析與設計-`--no-interaction`與非JSON輸入-結論.md

TypeScript interface defining the structure for non-interactive configuration, including project name, template, file removal lists, execution lists, and check arguments.

```typescript
interface NonInteractiveConfig {
  // Basic parameters
  name: string;                    // Project name
  template: string;                // Template source
  
  // Remove file list
  removeList: {
    field: string;                 // File/folder name
    isRemove: boolean;             // Whether to remove
  }[];
  
  // Execute command list
  execList: {
    key: string;                   // Command key (gitInit, npmInstall)
    command: string;               // Actual command
    isExec: boolean;               // Whether to execute
  }[];
  
  // Check parameters (corresponding to interactive confirmation)
  checkArgs: {
    husky: boolean;                // Keep husky
    github: boolean;               // Keep GitHub Actions
    gitInit: boolean;              // Execute git init
    npmInstall: boolean;           // Execute npm install
  };
}
```

--------------------------------

### Modified Files Summary

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/003_monorepo-default-config/_kilocode/20251217-TASK-START_TS_BY_004/implementation-summary.md

List of files modified and added as part of the implementation.

```text
Modified:
  M src/configs.ts                           (+2 lines)
  M src/utils/initProjPackageJson.ts         (+15 lines)
  M src/libs/createProject.ts                (+1 line)
  M src/commands/createAction/createAction.ts (+modified description)
  M src/commands/createAction/createAction.monorepo.test.ts

Added:
  A src/utils/initProjPackageJson.test.ts
  A openspec/changes/003_monorepo-default-config/_kilocode/20251217-TASK-START_TS_BY_004/technical-design.md
```

--------------------------------

### Non-interactive Mode - Basic Usage

Source: https://github.com/royfw/start-ts-by/blob/main/docs/README.md

Using the --no-interaction flag for non-interactive project creation.

```bash
# Using --no-interaction (--ni) flag
npx start-ts-by my-app -t royfw/starter-ts-app --no-interaction
npx start-ts-by my-app -t royfw/starter-ts-app --ni

# Legacy --skip-prompt flag (deprecated, use --no-interaction)
npx start-ts-by my-app --skip-prompt -t royfw/starter-ts-app

```

--------------------------------

### Jest unit tests

Source: https://github.com/royfw/start-ts-by/blob/main/docs/development.md

Commands to run Jest unit tests, including watch mode and web reports.

```sh
# src/**.(spec|test).ts
pnpm test
# or
pnpm test:watch 

```

```sh
# Unit Test Web Report, port:`9487`
```sh
pnpm test:web
```
# Coverage Web Report, port:`9488`
```sh
pnpm test:cov:web
```
```

--------------------------------

### Test execution plan

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/001_add-monorepo-flag/_kilocode/20250912-TASK-START_TS_BY_001-gpt5-分析專案、增加支援 `--no-interaction`/增加pnpm-workspace-yaml到monorepo移除清單-設計方案.md

Commands to execute tests and check coverage.

```bash
# 1. 執行單元測試
npm run test src/commands/createAction/createAction.monorepo.test.ts

# 2. 執行完整測試套件
npm test

# 3. 檢查測試覆蓋率
npm run test:coverage
```

--------------------------------

### Description in package.json

Source: https://github.com/royfw/start-ts-by/blob/main/openspec/changes/001_add-monorepo-flag/_kilocode/20250912-TASK-START_TS_BY_001-gpt5-分析專案、增加支援 `--no-interaction`/驗證 CLI help 與 README_docs 一致性-過程.md

The source code for the main command's description in package.json.

```typescript
export const configs: ProjectConfigType = {
  name: packageJson.name ?? 'my-cli',
  version: packageJson.version ?? '0.0.1',
  description: packageJson.description ?? 'my-cli', // 這裡是關鍵
  templates: getTemplates(),
  packageJson,
};
```