dsgn

Designator CLI

A command-line tool for educational institutions to rename files and folders according to standardized naming conventions.

Features

• 🏫 Multi-Institution Support: Fetch configuration from multiple educational institution hosts
• 🌐 Multi-Language Support: Complete support for Japanese and English
• 🔒 Secure Connections: HTTPS enforcement with SSL encryption required
• 📋 Rich Options: Specify lecture ID, student ID, surname, and submission date
• 🎯 Interactive Selection: Arrow key navigation and validation
• 📦 Automatic Processing: Handles both files and directories
• 🔄 Auto-conversion: HTTP to HTTPS automatic conversion when possible

Installation

npm install -g dsgn

Quick Start

Initial Setup

First-time users should configure their settings:

dsgn init

This will set up language preferences and host URLs.

Basic Usage

# Interactive mode
dsgn ./sample.json

# With options
dsgn ./sample.json -l 004 -si 000000 -n kazama -d 241225

Commands

Command	Description
dsgn <path> [options]	Rename file/folder according to naming rules
dsgn init	Initial setup (language and host configuration)
dsgn host	Manage API host settings
dsgn language	Change language settings
dsgn registry	Institution and course registration management
dsgn --help	Show help information
dsgn --version	Show version information

Options

Option	Short	Description	Example
-l <lectureId>		Specify lecture ID	-l 004
-si <studentId>		Specify student ID	-si 000000
-n <surname>		Specify surname	-n kazama
-d <submitDate>		Specify submission date	-d 241225
-y		Skip confirmation	-y
--version	-v	Show version
--help	-h	Show help

Host Management

# List hosts
dsgn host --list

# Add host
dsgn host --add https://example.com

# Remove host
dsgn host --remove 1

# Edit host
dsgn host --edit 1

Date Formats

Input Date Formats

The following date input formats are supported for the -d option:

• yymmdd (e.g., 241225)
• yyyymmdd (e.g., 20241225)
• mmdd (e.g., 1225)
• mdd (e.g., 125)
• mm/dd (e.g., 12/25)
• m/dd (e.g., 1/25)
• m/d (e.g., 1/5)

Custom Date Formatting in Folder Templates

Institutions can define custom date formats in their folderFormat templates using the following syntax:

Basic Date Placeholder

{date}

• Output: yyMMdd format (e.g., 250702)
• Description: Default 6-digit format (year-month-day)

Custom Date Format

{date(format)}

• Output: Custom formatted date string
• Description: Specify date-fns compatible format pattern

Supported Format Patterns

Pattern	Description	Example
yyyy	4-digit year	2025
yy	2-digit year	25
MM	2-digit month	07
M	1-2 digit month	7
dd	2-digit day	02
d	1-2 digit day	2

Custom Format Examples

# Template: {abbr}_{lectureName}{year}_{studentId}_{name}_{date(yyyy-MM-dd)}
# Output: stc_graphics25_123456_tanaka_2025-07-02

# Template: {abbr}_{lectureName}{year}_{studentId}_{name}_{date(yyyy_MM_dd)}
# Output: stc_graphics25_123456_tanaka_2025_07_02

# Template: {abbr}_{lectureName}{year}_{studentId}_{name}_{date(yyyyMMdd)}
# Output: stc_graphics25_123456_tanaka_20250702

Automatic Character Removal

For file/folder name compatibility, the following characters are automatically removed from custom date formats:

• File system forbidden characters: / \ : * ? " < > |
• Japanese characters: hiragana, katakana, kanji

# Template: {date(yyyy/MM/dd)} → automatically becomes {date(yyyyMMdd)}
# Template: {date(yyyy年MM月dd日)} → automatically becomes {date(yyyyMMdd)}

Host Requirements

API hosts must meet the following requirements:

• HTTPS Required: SSL encryption is mandatory (except localhost)
• Endpoint: /api/v1/configs must be available
• Domain Only: URLs with paths (e.g., https://example.com/path/) are not allowed
• Valid Response: Must return correct institution/lecture data

Supported URL Formats

✅ Valid URLs

https://example.com
https://example.com/
example.com
http://localhost:3000

❌ Invalid URLs

https://example.com/new/  # Paths not allowed
http://example.com          # HTTPS required (except localhost)
ftp://example.com           # Unsupported protocol

Auto-conversion Feature

URLs entered with HTTP are automatically converted to HTTPS if the /api/v1/configs endpoint is available:

# Input: http://example.com
# Auto-converted to: https://example.com/
dsgn host --add http://example.com

Configuration

Configuration is stored in ~/.dsgn.json:

{
  "hosts": ["https://example.com/"],
  "language": "en",
  "useArrowKeys": true
}

Data Storage

Institution and lecture data fetched from API endpoints is automatically cached in designator.json file in the Designator App's project root directory (same directory as package.json). This local cache improves performance and allows offline usage after initial setup.

The data structure stored in designator.json matches the API response format, containing:

• Institution information (name, abbreviation, system details)
• Lecture configurations (ID, name, type, naming format)
• Last update timestamps for cache management

API Integration

The CLI fetches institution and lecture data from REST API endpoints at /api/v1/configs, then converts and stores this data locally in designator.json. The expected API response format is:

{
  "success": true,
  "data": [
    {
      "id": "example123",
      "system": {
        "name": {
          "ja": "サンプル専門学校",
          "en": "Sample Technical College"
        },
        "abbr": "STC",
        "lowerAbbr": "stc"
      },
      "lectures": [
        {
          "id": "ABC123XY",
          "name": "graphics",
          "type": "",
          "label": {
            "ja": "グラフィックデザイン（2025年度 火曜日 1,2限）",
            "en": "Graphic Design (FY2025 Tuesday 1st & 2nd Period)"
          },
          "folderFormat": "{abbr}_{lectureName}{year}_{studentId}_{name}_{date}"
        }
      ]
    }
  ],
  "total": 1
}

Examples

Interactive Mode

dsgn ./project-folder/
# Follow prompts to select institution, lecture, enter student details
# Output: stc_graphics25_123456_tanaka_250630/

Batch Mode

dsgn ./report.pdf -l ABC123XY -si 123456 -n tanaka -d 20250630 -y
# Output: stc_graphics25_123456_tanaka_250630.pdf

Date Format Examples

# Both input formats are accepted
dsgn ./file.txt -d 250630    # 6-digit format (yymmdd)
dsgn ./file.txt -d 20250630  # 8-digit format (yyyymmdd)
# Both output: filename_250630.ext