npm package: @karenore/ollama-cli
Description: Ollama와 연계되는 CLI 개발 도구
Author: Ollama CLI Team
Latest version: 1.0.4

# Ollama CLI

> Ollama와 연계되는 강력한 CLI 개발 도구

Ollama CLI는 Ollama AI 모델과 상호작용하기 위한 포괄적인 명령줄 인터페이스입니다. 대화형 채팅, 코드 생성, 설정 관리 등의 기능을 제공하여 AI 모델을 효율적으로 활용할 수 있습니다.

## 🚀 주요 기능

- **대화형 채팅**: 실시간으로 AI 모델과 대화
- **코드 생성**: 다양한 프로그래밍 언어와 프레임워크 지원
- **설정 관리**: 백업, 복원, 검증 기능을 포함한 완전한 설정 관리
- **파일 처리**: 파일 I/O, 백업, 패턴 매칭 등 다양한 파일 처리 기능
- **풍부한 템플릿**: React, Express, Python, Vue, Go 등 다양한 템플릿 지원

## 📋 목차

- [설치](#설치)
- [빠른 시작](#빠른-시작)
- [명령어](#명령어)
- [설정](#설정)
- [사용 예제](#사용-예제)
- [개발](#개발)
- [문제 해결](#문제-해결)
- [기여](#기여)
- [라이선스](#라이선스)

## 🔧 설치

### 필수 요구사항

- Node.js 18.0 이상
- npm 또는 yarn
- [Ollama](https://ollama.ai) 설치 및 실행

### 설치 방법

```bash
# 저장소 클론
git clone https://github.com/your-username/ollama-cli.git
cd ollama-cli

# 의존성 설치
npm install

# 빌드
npm run build

# 글로벌 설치 (선택사항)
npm install -g .
```

## ⚡ 빠른 시작

1. **Ollama 서버 실행**
   ```bash
   ollama serve
   ```

2. **서버 상태 확인**
   ```bash
   npm run dev status
   ```

3. **대화형 채팅 시작**
   ```bash
   npm run dev chat
   ```

4. **코드 생성**
   ```bash
   npm run dev generate --prompt "React 컴포넌트 생성"
   ```

## 📖 명령어

### 🔄 `status` - 서버 상태 확인

Ollama 서버의 상태와 사용 가능한 모델을 확인합니다.

```bash
npm run dev status
```

**출력 예시:**
```
📊 Ollama Server Status
🟢 서버 상태: 연결됨
📋 버전: 0.1.0
🤖 사용 가능한 모델: 3개
  - llama2 (3.8GB)
  - codellama (3.8GB)
  - mistral (4.1GB)
```

### 💬 `chat` - 대화형 채팅

AI 모델과 실시간 대화를 시작합니다.

```bash
npm run dev chat [옵션]
```

**옵션:**
- `-m, --model <model>`: 사용할 모델 (기본값: phi3:mini)
- `-s, --system <prompt>`: 시스템 프롬프트 설정
- `-t, --temperature <number>`: 응답 창의성 조절 (0.0-1.0)
- `--max-tokens <number>`: 최대 토큰 수

**채팅 내 명령어:**
- `/help`: 도움말 표시
- `/clear`: 대화 기록 초기화
- `/history`: 대화 기록 표시
- `/model`: 모델 변경
- `/models`: 사용 가능한 모델 목록
- `/save`: 대화 기록 저장
- `/exit, /quit`: 채팅 종료

**사용 예시:**
```bash
# 기본 채팅
npm run dev chat

# 특정 모델로 채팅
npm run dev chat -m codellama

# 시스템 프롬프트와 함께
npm run dev chat -s "당신은 도움이 되는 프로그래밍 어시스턴트입니다"
```

### 🔧 `generate` - 코드 생성

AI를 사용해 다양한 코드를 생성합니다.

```bash
npm run dev generate [옵션]
```

**옵션:**
- `-f, --file <file>`: 생성할 파일 경로
- `-p, --prompt <prompt>`: 코드 생성 프롬프트
- `-m, --model <model>`: 사용할 모델
- `-l, --language <language>`: 프로그래밍 언어
- `--framework <framework>`: 프레임워크
- `--template <template>`: 템플릿 사용
- `--output-dir <dir>`: 출력 디렉토리

**지원 템플릿:**
- `react-component`: React 함수형 컴포넌트
- `express-api`: Express.js API 엔드포인트
- `python-class`: Python 클래스
- `vue-component`: Vue.js 컴포넌트
- `go-handler`: Go HTTP 핸들러

**사용 예시:**
```bash
# 프롬프트로 코드 생성
npm run dev generate -p "사용자 인증 API 엔드포인트"

# 템플릿 사용
npm run dev generate --template react-component

# 특정 파일로 저장
npm run dev generate -p "계산기 클래스" -f calculator.py
```

### ⚙️ `config` - 설정 관리

애플리케이션 설정을 관리합니다.

```bash
npm run dev config [옵션]
```

**옵션:**
- `-l, --list`: 모든 설정 조회
- `-g, --get <key>`: 특정 설정 값 조회
- `-s, --set <key=value>`: 설정 값 설정
- `--reset`: 모든 설정 초기화
- `--validate`: 설정 검증
- `--export <file>`: 설정 내보내기
- `--import <file>`: 설정 가져오기
- `--backup`: 설정 백업
- `--restore <file>`: 백업에서 복원

**설정 섹션:**
- `ollama.*`: Ollama 서버 설정
- `ui.*`: UI 관련 설정
- `codegen.*`: 코드 생성 설정
- `history.*`: 히스토리 관리 설정
- `logging.*`: 로깅 설정

**사용 예시:**
```bash
# 모든 설정 보기
npm run dev config --list

# 특정 설정 조회
npm run dev config --get ollama.baseUrl

# 설정 변경
npm run dev config --set ollama.baseUrl=http://localhost:11434
npm run dev config --set ui.theme=dark

# 설정 검증
npm run dev config --validate

# 백업 및 복원
npm run dev config --backup
npm run dev config --restore config.backup.2024-01-01.json
```

### 📥 `pull` - 모델 다운로드

새로운 모델을 다운로드합니다.

```bash
npm run dev pull <model-name>
```

**사용 예시:**
```bash
# 모델 다운로드
npm run dev pull llama2
npm run dev pull codellama:7b
npm run dev pull mistral
```

## 🔧 설정

### 설정 파일 위치

기본 설정 파일은 `~/.ollama-cli/config.json`에 저장됩니다.

### 주요 설정 항목

```json
{
  "ollama": {
    "baseUrl": "http://localhost:11434",
    "timeout": 60000,
    "defaultModel": "phi3:mini",
    "maxRetries": 3
  },
  "ui": {
    "theme": "light",
    "language": "ko",
    "showTimestamp": true,
    "autoSave": true
  },
  "codegen": {
    "defaultLanguage": "typescript",
    "defaultFramework": "none",
    "outputDir": "./generated",
    "templates": {}
  },
  "history": {
    "maxEntries": 1000,
    "autoCleanup": true,
    "saveLocation": "~/.ollama-cli/history"
  },
  "logging": {
    "level": "info",
    "maxFileSize": 10485760,
    "maxFiles": 5
  }
}
```

## 💡 사용 예제

### 1. 대화형 개발 어시스턴트

```bash
# 코딩 어시스턴트 시작
npm run dev chat -m codellama -s "당신은 전문 개발자입니다. 코드 리뷰, 디버깅, 최적화에 도움을 주세요."

# 채팅 내에서
사용자: 이 Python 코드를 최적화해주세요
[코드 붙여넣기]

어시스턴트: [최적화된 코드와 설명 제공]
```

### 2. 빠른 코드 생성

```bash
# React 컴포넌트 생성
npm run dev generate --template react-component

# 구체적인 요구사항 입력
> React 함수형 컴포넌트에 대한 구체적인 요구사항을 입력하세요:
> 사용자 프로필 카드 컴포넌트, 아바타 이미지와 이름, 이메일 표시

# 생성된 코드가 파일로 저장됨
✅ 코드가 UserProfileCard.tsx에 저장되었습니다.
```

### 3. 설정 관리 워크플로우

```bash
# 현재 설정 백업
npm run dev config --backup
✅ 설정이 백업되었습니다: ~/.ollama-cli/config.backup.2024-01-01.json

# 설정 변경
npm run dev config --set ollama.baseUrl=http://custom-server:8080
npm run dev config --set ui.theme=dark

# 설정 검증
npm run dev config --validate
✅ 설정이 유효합니다.

# 문제가 있을 경우 백업에서 복원
npm run dev config --restore ~/.ollama-cli/config.backup.2024-01-01.json
```

## 🛠️ 개발

### 개발 환경 설정

```bash
# 개발 모드 실행
npm run dev

# 테스트 실행
npm test

# 린트 검사
npm run lint

# 타입 검사
npm run typecheck
```

### 디렉토리 구조

```
ollama-cli/
├── src/
│   ├── cli/                 # CLI 명령어 처리
│   ├── core/                # 핵심 기능 모듈
│   ├── utils/               # 유틸리티 함수
│   ├── types/               # TypeScript 타입 정의
│   └── index.ts             # 메인 진입점
├── tests/                   # 테스트 파일
├── docs/                    # 문서
├── logs/                    # 로그 파일
└── dist/                    # 빌드 결과물
```

### 코딩 스타일

- TypeScript 사용
- 함수명과 변수명: camelCase
- 클래스명: PascalCase
- 상수: UPPER_CASE
- 파일명: kebab-case

## 🔧 문제 해결

### 1. Ollama 서버 연결 실패

```bash
# 서버 상태 확인
npm run dev status

# Ollama 서버 시작 (별도 터미널)
ollama serve
```

### 2. 모델이 없는 경우

```bash
# 모델 다운로드
npm run dev pull llama2
```

### 3. 권한 오류

```bash
# 실행 권한 부여
chmod +x dist/index.js
```

### 4. 로그 확인

로그 파일은 `./logs/` 디렉토리에 저장됩니다:
- `error.log`: 에러 로그
- `combined.log`: 모든 로그
- `YYYY-MM-DD.log`: 날짜별 로그

### 5. 지원되는 모델

Ollama에서 지원하는 모든 모델을 사용할 수 있습니다:
- phi3:mini (기본값)
- llama2
- codellama
- mistral
- neural-chat
- qwen2.5-coder:1.5b-base
- gemma3:latest
- 기타 Ollama 지원 모델

모델 목록 확인:
```bash
npm run dev status
```

## 🤝 기여

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 라이선스

이 프로젝트는 MIT 라이선스하에 배포됩니다. 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.

## 🙏 감사의 말

- [Ollama](https://ollama.ai) - AI 모델 런타임 제공
- [Commander.js](https://github.com/tj/commander.js) - CLI 프레임워크
- [Inquirer.js](https://github.com/SBoudrias/Inquirer.js) - 대화형 프롬프트
- [Winston](https://github.com/winstonjs/winston) - 로깅 라이브러리

## 📞 지원

문제가 발생하거나 질문이 있으시면 [Issues](https://github.com/your-username/ollama-cli/issues)에서 문의해주세요.

---

**Made with ❤️ by the Ollama CLI Team**