npm package: @manyfast/cli
Description: Manyfast CLI - AI agent-friendly interface for Manyfast project data
Latest version: 0.2.2

# @manyfast/cli

AI 에이전트 친화적인 Manyfast 프로젝트 데이터 인터페이스.

프로젝트의 기획 데이터(PRD → 요구사항 → 기능 → 스펙)를 CLI로 조회·편집·내보내기할 수 있습니다. stdout/stderr 분리, JSON/YAML/Markdown 출력을 지원하여 AI 에이전트(Claude Code, Cursor 등)와의 파이프라인 연동에 최적화되어 있습니다.

## 설치

```bash
npm install -g @manyfast/cli
# 또는
npx @manyfast/cli
```

## 인증

API Key(`mf_sk_` 접두사)로 인증합니다.

```bash
# 로그인
manyfast auth login --api-key mf_sk_your_key_here

# 인증 상태 확인
manyfast auth status

# 로그아웃
manyfast auth logout
```

인증 정보는 `~/.manyfast/credentials.json`에 저장됩니다 (파일 권한 0600).

## 글로벌 옵션

| 옵션 | 설명 | 기본값 |
|------|------|--------|
| `--api-url <url>` | API URL 오버라이드 | `https://api.manyfast.io` |
| `--api-key <key>` | API Key 직접 지정 (저장된 키 대신 사용) | — |
| `--format <fmt>` | 출력 포맷: `json`, `yaml`, `md` | `json` |
| `--quiet` | stderr 출력 억제 | — |
| `--verbose` | 디버그 정보 표시 | — |

## 명령어

### project — 프로젝트 관리

```bash
# 프로젝트 목록
manyfast project list [--limit <n>] [--deleted]

# 프로젝트 상세 조회 (PRD, 요구사항, 기능, 스펙 포함)
manyfast project get <projectId>

# 프로젝트 생성
manyfast project create "프로젝트 제목" [--description "설명"]

# 프로젝트 검색
manyfast project search "검색어"

# 프로젝트 삭제 (soft delete)
manyfast project delete <projectId>
```

### prd — PRD (기획서) 관리

```bash
# PRD 조회
manyfast prd get <projectId>

# PRD 전체 작성/수정
manyfast prd write <projectId> --file prd.json [--mode create|update]

# PRD 섹션별 수정
manyfast prd write-section <projectId> --section overview --file section.json
# 섹션: overview | coreValue | target | success | attribute
```

<details>
<summary>PRD 입력 JSON 스키마</summary>

```json
{
  "category": "productivity",
  "subject": "프로젝트 한 줄 소개",
  "goal": "목표",
  "targetUser": "대상 사용자",
  "background": "배경",
  "userProblem": "사용자 문제",
  "solution": "솔루션",
  "differentiation": "차별점",
  "scenario": "사용 시나리오",
  "kpi": "핵심 지표",
  "risk": "리스크",
  "devices": [{ "name": "Web", "id": null }],
  "roles": [{ "name": "User", "id": null }]
}
```

| 섹션 | 필드 |
|------|------|
| `overview` | category, subject |
| `coreValue` | goal, targetUser, background, userProblem, solution, differentiation |
| `target` | devices, roles |
| `success` | scenario, kpi |
| `attribute` | risk |

</details>

### requirement — 요구사항 관리

```bash
# 요구사항 목록
manyfast requirement list <projectId>

# 요구사항 생성/수정 (최대 10개)
manyfast requirement write <projectId> --file requirements.json [--mode create|update]

# 요구사항 삭제 (하위 기능·스펙 cascade 삭제)
manyfast requirement delete <projectId> R-abc123 [R-def456 ...]
```

<details>
<summary>요구사항 입력 JSON 스키마</summary>

```json
[
  {
    "name": "요구사항 이름",
    "description": "설명",
    "acceptanceCriteria": [
      { "description": "인수 기준", "isDone": false }
    ],
    "importance": "high",
    "progress": "todo",
    "id": "R-XXXXXX"
  }
]
```

- `id`는 `--mode update` 시 필수
- `importance`: `high` | `medium` | `low`
- `progress`: `todo` | `in-progress` | `done` | `blocked`

</details>

### feature — 기능 관리

```bash
# 기능 목록
manyfast feature list <projectId>

# 기능 생성/수정 (최대 10개)
manyfast feature write <projectId> --file features.json [--mode create|update]

# 기능 삭제 (하위 스펙 cascade 삭제)
manyfast feature delete <projectId> F-abc123 [F-def456 ...]
```

<details>
<summary>기능 입력 JSON 스키마</summary>

```json
[
  {
    "parentId": "R-XXXXXX",
    "name": "기능 이름",
    "description": "설명",
    "roles": ["ROLE_ID"],
    "devices": ["DEVICE_ID"],
    "importance": "high",
    "progress": "todo",
    "id": "F-XXXXXX"
  }
]
```

- `parentId`: 상위 요구사항 ID (생성 시 필수)
- `id`는 `--mode update` 시 필수

</details>

### spec — 스펙 관리

```bash
# 스펙 목록
manyfast spec list <projectId>

# 스펙 생성/수정 (최대 10개)
manyfast spec write <projectId> --file specs.json [--mode create|update]

# 스펙 삭제
manyfast spec delete <projectId> S-abc123 [S-def456 ...]
```

<details>
<summary>스펙 입력 JSON 스키마</summary>

```json
[
  {
    "parentId": "F-XXXXXX",
    "name": "스펙 이름",
    "description": "설명",
    "roles": ["ROLE_ID"],
    "devices": ["DEVICE_ID"],
    "importance": "high",
    "progress": "todo",
    "id": "S-XXXXXX"
  }
]
```

- `parentId`: 상위 기능 ID (생성 시 필수)
- `id`는 `--mode update` 시 필수

</details>

### export — 프로젝트 전체 내보내기

```bash
# 전체 내보내기
manyfast export <projectId>

# 섹션 선택 내보내기
manyfast export <projectId> --include prd,requirements,features

# Markdown으로 내보내기
manyfast export <projectId> --format md
```

`--include` 옵션: `prd`, `requirements`, `features`, `specs`, `user-flows` (쉼표 구분, 기본값: `prd,requirements,features,specs`)

### user-flow — 유저 플로우 조회

```bash
# 유저 플로우 그룹/버전 목록
manyfast user-flow list <projectId>

# 특정 버전의 유저 플로우 상세 (노드/엣지)
manyfast user-flow get <projectId> <versionId>
```

### comment — 코멘트 관리

```bash
# 프로젝트 전체 코멘트 목록
manyfast comment list <projectId> [--include-resolved] [--limit 20] [--cursor <id>]

# 특정 항목의 코멘트
manyfast comment list-item <projectId> R-abc123 [--include-resolved]

# 코멘트 작성
manyfast comment create <projectId> --file comment.json

# 코멘트 수정
manyfast comment update <projectId> <commentId> --file comment.json

# 코멘트 삭제
manyfast comment delete <projectId> <commentId>

# 코멘트 resolve 토글
manyfast comment resolve <projectId> <commentId>
```

### version — 버전 이력 관리

```bash
# 버전 목록
manyfast version list <projectId> [--limit 20] [--cursor <id>]

# 버전 상세
manyfast version get <projectId> <versionId>

# 버전 메시지 수정
manyfast version update <projectId> <versionId> --file version.json
```

### init — AI 에이전트 스킬 설치

[Agent Skills 개방형 표준](https://agentskills.io) 기반으로 스킬 파일을 설치합니다.

```bash
# 기본: .agents/skills/ (cross-agent) + 자동 감지된 에이전트 네이티브 경로
manyfast init

# 특정 에이전트만 설치
manyfast init --agent claude
manyfast init --agent windsurf
manyfast init --agent all

# 스킬 파일 제거
manyfast uninit
manyfast uninit --agent claude
manyfast uninit --cleanup           # 레거시 파일도 제거
```

| 경로 | 설명 |
|------|------|
| `.agents/skills/manyfast/` | Cross-agent 표준 (Codex, Cursor, Gemini 스캔) |
| `.claude/skills/manyfast/` | Claude Code 전용 (`.claude/` 감지 시 자동 설치) |
| `.windsurf/skills/manyfast/` | Windsurf 전용 (`.windsurf/` 감지 시 자동 설치) |

## 입출력 규칙

### stdout / stderr 분리

- **stdout**: 데이터 출력 (`--format`에 따라 JSON/YAML/Markdown)
- **stderr**: 상태 메시지, 에러 (항상 JSON)
- **`--quiet`**: stderr 출력 억제

파이프 연동 시 데이터만 깔끔하게 전달됩니다:

```bash
# 프로젝트 데이터를 파일로 저장
manyfast export abc123 --format md > project.md

# jq로 특정 필드 추출
manyfast project get abc123 | jq '.prd.subject'

# 다른 명령어에 파이프
manyfast requirement list abc123 | jq '.[].name'
```

### 입력 방식

```bash
# 파일에서 읽기 (JSON 또는 YAML)
manyfast prd write abc123 --file prd.json
manyfast prd write abc123 --file prd.yaml

# stdin 파이프
echo '{"subject":"My Project"}' | manyfast prd write abc123

# heredoc
manyfast requirement write abc123 <<'EOF'
[{"name": "인증 기능", "importance": "high", "progress": "todo"}]
EOF
```

## 종료 코드

| 코드 | 의미 | 상황 |
|------|------|------|
| `0` | 성공 | 정상 완료 |
| `1` | 에러 | API 또는 처리 오류 |
| `2` | 인증 에러 | API Key 없음, 유효하지 않음, 401/403 |
| `3` | 리소스 없음 | 404 (프로젝트 등) |

## 설정 파일

| 파일 | 위치 | 용도 |
|------|------|------|
| `config.json` | `~/.manyfast/` | API URL, 기본 포맷 등 사용자 설정 |
| `credentials.json` | `~/.manyfast/` | API Key 저장 (권한 0600) |

## 데이터 계층 구조

```
Project
├── PRD (기획서)
├── Requirement (R-XXXXXX)
│   └── Feature (F-XXXXXX)
│       └── Spec (S-XXXXXX)
├── User Flow
├── Comment
└── Version
```

상위 항목 삭제 시 하위 항목이 cascade 삭제됩니다.

## 라이선스

[MIT](./LICENSE)