Raycast에서 Snowflake ID 생성하기 (Script Command)
❄️

Raycast에서 Snowflake ID 생성하기 (Script Command)

Created
2026/05/11
Tags
Python
Tip
mac
 
2026-05-11 @이영훈
 

개요

개발 중에 Snowflake ID를 직접 생성해야 할 때가 종종 있어요. 테스트 데이터를 만들 때, DB에 더미 데이터를 넣을 때, 로컬에서 API 호출 시 ID가 필요할 때...
그때마다 IDE를 열고 Kotlin 코드를 돌리는 건 번거롭습니다. 그래서 Raycast Script Command로 만들어두고, 단축키 한 번에 ID 여러 개를 클립보드로 복사하도록 했어요.
 
❄️
Raycast의 Script Command 기능을 사용하면 Python/Bash/AppleScript 등으로 커스텀 명령어를 만들어 Raycast에서 실행할 수 있습니다.
 
 

본문

완성된 모습

Raycast에서 Generate Snowflake IDs를 검색하면 다음과 같이 표시됩니다. argument로 개수(기본값 5)를 받고, 실행하면 ID들이 클립보드에 복사돼요.
notion image
  • ❄️ 아이콘
  • argument: count (default: 5)
  • Developer Utils 패키지로 그룹화
  • 실행 시 silent 모드 → 별도 창 없이 토스트로 결과 표시

Raycast Script Command 메타데이터

Raycast Script Command는 파일 상단의 주석(@raycast.*)으로 메타데이터를 정의해요.
Python
#!/usr/bin/env python3

# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title Generate Snowflake IDs
# @raycast.mode silent

# Optional parameters:
# @raycast.icon ❄️
# @raycast.argument1 { "type": "text", "placeholder": "count (default: 5)", "optional": true }
# @raycast.packageName Developer Utils

# Documentation:
# @raycast.description Generate N Snowflake IDs (Crockford Base32) and copy to clipboard
 
주요 옵션은 다음과 같습니다.
  • @raycast.mode: silent / compact / fullOutput 중 선택
  • @raycast.argument1: 사용자 입력을 받는 argument 정의
  • @raycast.icon: 이모지나 이미지 파일 경로 지정
  • @raycast.packageName: Raycast 내에서 같은 그룹으로 묶임
 

Python으로 Snowflake ID 구현

Kotlin 구현과 동일한 알고리즘을 Python으로 옮겼습니다. Machine ID는 MAC 주소(uuid.getnode()) + PID를 MD5로 해싱하여 생성해요.
Python
import sys
import time
import os
import subprocess
import uuid
import hashlib

EPOCH = 1288834974657  # Twitter Snowflake epoch (2010-11-04T01:42:54.657Z)
MACHINE_ID_BITS = 10
SEQUENCE_BITS = 12
MAX_MACHINE_ID = (1 << MACHINE_ID_BITS) - 1
MAX_SEQUENCE = (1 << SEQUENCE_BITS) - 1
TIMESTAMP_SHIFT = MACHINE_ID_BITS + SEQUENCE_BITS
MACHINE_ID_SHIFT = SEQUENCE_BITS

CROCKFORD_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz"


def get_machine_id():
    raw = hashlib.md5(f"{uuid.getnode()}-{os.getpid()}".encode()).digest()
    value = int.from_bytes(raw[:4], "big")
    return value & MAX_MACHINE_ID


machine_id = get_machine_id()
sequence = int.from_bytes(os.urandom(2), "big") & MAX_SEQUENCE
last_timestamp = -1


def next_id():
    global sequence, last_timestamp

    timestamp = int(time.time() * 1000)

    if timestamp < last_timestamp:
        raise RuntimeError("Clock moved backwards")

    if timestamp == last_timestamp:
        sequence = (sequence + 1) & MAX_SEQUENCE
        if sequence == 0:
            while timestamp <= last_timestamp:
                timestamp = int(time.time() * 1000)
    else:
        sequence = (sequence + 1) & MAX_SEQUENCE

    last_timestamp = timestamp

    id_val = (
        ((timestamp - EPOCH) << TIMESTAMP_SHIFT)
        | (machine_id << MACHINE_ID_SHIFT)
        | sequence
    )
    return encode_crockford_base32(id_val)


def encode_crockford_base32(value):
    byte_data = value.to_bytes(8, byteorder="big")
    result = []
    buffer = 0
    bits_in_buffer = 0

    for b in byte_data:
        buffer = (buffer << 8) | b
        bits_in_buffer += 8
        while bits_in_buffer >= 5:
            index = (buffer >> (bits_in_buffer - 5)) & 0x1F
            result.append(CROCKFORD_ALPHABET[index])
            bits_in_buffer -= 5

    if bits_in_buffer > 0:
        index = (buffer << (5 - bits_in_buffer)) & 0x1F
        result.append(CROCKFORD_ALPHABET[index])

    return "".join(result)


def main():
    count = 5
    if len(sys.argv) > 1 and sys.argv[1].strip():
        try:
            count = int(sys.argv[1].strip())
        except ValueError:
            print("Invalid count, using default 5")
            count = 5

    count = max(1, min(count, 1000))

    ids = [next_id() for _ in range(count)]
    output = "\n".join(ids)

    subprocess.run(["pbcopy"], input=output.encode(), check=True)
    print(f"Copied {count} Snowflake IDs to clipboard")


if __name__ == "__main__":
    main()
 
Kotlin 버전과 동일한 알고리즘이지만 몇 가지 차이가 있습니다.
  • Machine ID 생성을 hashlib.md5(MAC + PID)로 단순화
  • subprocess.run(["pbcopy"], ...) 로 macOS 클립보드에 직접 복사
  • argument로 받은 개수만큼 ID를 한 번에 생성 (1~1000개 제한)
 

설치 방법

  1. Raycast 설정 → Extensions → Script Commands 열기
  1. Add Script Directories 클릭, snowflake-id-generator 폴더 선택
  1. Raycast에서 Generate Snowflake IDs 검색하여 사용
 

사용법

  1. Raycast 열기 (⌘ + Space 또는 Option + Space)
  1. Generate Snowflake IDs 검색
  1. argument에 생성할 개수 입력 (선택, 기본값 5)
  1. ⏎ 누르면 클립보드에 ID 목록이 복사됨
 
예를 들어 5개를 생성하면 클립보드에는 다음처럼 들어가요.
javascript
3qkpc7gh8n4m2
3qkpc7gh8n4m5
3qkpc7gh8n4m8
3qkpc7gh8n4mb
3qkpc7gh8n4me
 

ID 구조 복습

javascript
 64-bit Snowflake ID
├─ 42 bits ─┤─ 10 bits ─┤─ 12 bits ─┤
  timestamp   machine_id   sequence
  • Timestamp: epoch(2010-11-04T01:42:54.657Z)부터 경과한 밀리초
  • Machine ID: MAC 주소 + PID의 MD5 해시, 10비트 마스킹
  • Sequence: 밀리초 단위 카운터 (0~4095)
 

활용 팁

  • Hotkey 등록: Raycast 설정에서 이 커맨드에 단축키를 매핑하면 키 한 번에 ID 발급
  • package 그룹화: @raycast.packageName Developer Utils 로 묶어두면 비슷한 개발 도구 스크립트를 한 곳에서 관리 가능
  • 확장 아이디어: argument를 추가해서 ID 형식(Base32 / Long / UUID 등)을 선택하도록 만들 수도 있음