based

based is a small CLI for adding local project templates into an existing directory.

It only supports local template repositories in the current version. The main command is based add, so the same target directory can receive multiple templates over time.

English | 简体中文

Installation

npm install -g @chin0102/based-cli

Check the CLI:

based --help

Quick Start

Configure your local template repository:

based config set templatesDir ~/workspace/based-templates

List available templates:

based list

Add a template into the current directory:

based add vue-admin

Add a template into a specific directory:

based add vue-admin ./apps/admin

Commands

based add

Add a local template into a target directory.

based add
based add <template>
based add <template> <targetDir>

Options:

based add vue-admin ./apps/admin --skip-existing
based add vue-admin ./apps/admin --overwrite

Behavior:

• If template is omitted, the CLI prompts you to select one.
• If targetDir is omitted, the current working directory is used.
• The same target directory can be used multiple times.
• New files are written directly.
• Existing files with the same content are skipped.
• Existing files with different content are handled by conflict mode.

Conflict modes:

• Default: prompt to overwrite, skip, or abort.
• --skip-existing: skip conflicting files.
• --overwrite: overwrite conflicting files.

based add never deletes the whole target directory.

based list

List templates from the configured local template repository.

based list

Example output:

vue-admin    Vue admin template
node-api     Node API template

based config

Manage local CLI configuration.

based config set templatesDir ~/workspace/based-templates
based config get templatesDir
based config list

Configuration is stored at:

~/.based/config.json

For tests or CI, override the config directory:

BASED_CONFIG_DIR=/tmp/based-config based list

Template Repository

A template repository is a local directory. Each first-level subdirectory is one template.

Example:

~/workspace/based-templates/
├─ vue-admin/
│  ├─ template/
│  │  ├─ .codex/
│  │  │  └─ skills/
│  │  │     └─ vue-admin/
│  │  │        └─ SKILL.md
│  │  ├─ package.json
│  │  ├─ src/
│  │  └─ README.md
│  └─ meta.json
│
└─ node-api/
   ├─ template/
   │  ├─ package.json
   │  └─ src/
   └─ meta.json

Rules:

• A template must contain a template/ directory.
• meta.json is optional.
• The template name is the directory name, such as vue-admin.
• Template files may include project-specific Codex skills, such as .codex/skills/vue-admin/SKILL.md.

Template With SKILL.md

If a template should also add a Codex Skill to the target project, place the skill under the template directory:

vue-admin/
├─ template/
│  └─ .codex/
│     └─ skills/
│        └─ vue-admin/
│           └─ SKILL.md
└─ meta.json

Example SKILL.md:

# Vue Admin

Use this skill when working inside a project generated from the vue-admin template.

## Guidelines

- Follow the existing Vue component and routing structure.
- Put reusable UI in `src/components`.
- Put page-level views in `src/views`.
- Use the configured package manager: `{{packageManager}}`.

Because SKILL.md is a normal template file, render it explicitly in meta.json if it contains variables:

{
  "render": {
    "content": [
      ".codex/skills/vue-admin/SKILL.md"
    ]
  }
}

If the skill file does not contain variables, omit it from render.content and it will be copied as-is.

Template Metadata

meta.json describes a template, the prompts used when adding it, and which files should be rendered.

{
  "name": "vue-admin",
  "description": "Vue admin template",
  "prompts": [
    {
      "name": "projectName",
      "type": "input",
      "message": "Project name",
      "default": "my-app",
      "required": true
    },
    {
      "name": "description",
      "type": "input",
      "message": "Description",
      "default": "A new project"
    },
    {
      "name": "packageManager",
      "type": "list",
      "message": "Package manager",
      "choices": ["pnpm", "npm", "yarn"],
      "default": "pnpm"
    }
  ],
  "render": {
    "content": {
      "include": [
        "package.json",
        "README.md",
        "src/**/*.ts"
      ],
      "exclude": [
        "src/vendor/**"
      ]
    },
    "path": {
      "include": [
        "{{projectName}}.config.js",
        "src/{{moduleName}}/**"
      ]
    }
  }
}

Supported prompt types:

• input
• confirm
• list

If meta.json is missing or has no prompts, projectName defaults to the target directory name.

Template Variables

Template files use Handlebars variables. Variables are rendered only for files explicitly declared in meta.json.

Template file:

{
  "name": "{{projectName}}",
  "description": "{{description}}"
}

Generated file:

{
  "name": "demo-app",
  "description": "Demo project"
}

File and directory names can also use variables:

template/
├─ {{projectName}}.config.js
└─ src/{{moduleName}}/

Render Rules

The CLI does not guess which files should be rendered. Template authors must declare render rules in meta.json.

Render file content:

{
  "render": {
    "content": ["package.json", "README.md", "src/**/*.ts"]
  }
}

Render file or directory paths:

{
  "render": {
    "path": ["{{projectName}}.config.js", "src/{{moduleName}}/**"]
  }
}

Use include and exclude rules:

{
  "render": {
    "content": {
      "include": ["**/*"],
      "exclude": ["public/**", "**/*.png", "**/*.jpg"]
    },
    "path": {
      "include": ["**/{{projectName}}*"]
    }
  }
}

Rules use glob patterns relative to the template template/ directory.

Supported forms:

• render.content: files whose contents should be rendered.
• render.path: files or directories whose relative path should be rendered.
• Rule value can be an array of glob patterns.
• Rule value can also be an object with include and exclude.

Files that are not matched by render.content are copied as-is. Paths that are not matched by render.path are copied with their original names.

TODO

These items are described or implied by the usage docs, but are not fully implemented yet:

• Validate meta.json and show clear errors for invalid prompts or render rules.
• Support non-interactive prompt values for scripts and CI, such as --var projectName=demo.
• Add stronger protection when render.content points to binary files.