> For the complete documentation index, see [llms.txt](https://orbitron.gitbook.io/orbitron-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://orbitron.gitbook.io/orbitron-docs/documentation/ko/user-guide/usage.md).
# 사용법
Orbitron은 다양한 워크플로와 환경을 수용하기 위해 두 가지 주요 작동 모드를 지원합니다:
### **🔗 1. 대화형 모드**
대화형 모드는 Orbitron의 **기본 사용 환경**으로, AI와 실시간 상호작용하며 단계별로 작업을 진행할 수 있습니다.\
이 모드는 특히 **Orbitron을 처음 사용하는 사용자**나 **실시간으로 AI의 도움을 받으며 복잡한 작업을 수행해야 하는 경우** 적합합니다.
* **단계별 안내**: 명령 입력뿐 아니라 AI가 적절한 단계로 안내
* **학습 및 탐색에 이상적**: 새로운 클라우드 명령어 학습, 실험적 워크플로 수행 가능
* **옵션 사전 정의 불필요**: 실행 중 AI와 대화를 통해 필요한 정보 수집 및 선택 가능
사용 예시:
```bash
# Orbitron 실행
orbitron
# 특정 작업 디렉토리로 지정
orbitron -c /path/to/project
```
이렇게 하면 Orbitron이 대화형 터미널 세션으로 시작됩니다.
***
### 📋 2. 컨텍스트와 함께하는 대화형 모드
Orbitron은 프로젝트별 또는 대화별 컨텍스트를 저장하고 관리하도록 설계된 내장 **메모리 파일 시스템**을 제공합니다.
이를 통해 AI가 이전 세션의 정보를 기억하고, 반복 작업에서 **일관된 결과**를 제공할 수 있습니다.
***
#### 📁 `orbitron.md` – 메모리 파일
Orbitron의 컨텍스트는 Supabase를 통해 관리됩니다. 프로젝트 디렉토리에 `orbitron.md` 파일을 생성하여 로컬에서 컨텍스트를 관리할 수도 있습니다.
**📝 컨텍스트의 목적:**
* **프로젝트 목표**, **구성**, **주요 결정사항**, **AI 대화 요약**을 저장합니다.
* Supabase 또는 로컬 파일(`orbitron.md`)을 통해 관리됩니다.
* AI와의 후속 상호작용에서 **컨텍스트 인식**을 향상시킵니다.
> 💡 **참고**: 컨텍스트 관리 방식은 사용자의 설정에 따라 달라질 수 있습니다. 기본적으로 Supabase를 통해 관리되지만, 로컬 파일을 통한 관리도 가능합니다.
이를 통해 Orbitron이 사용자의 작업을 "기억"하고 그에 맞게 응답할 수 있습니다.
***
#### ⚙️ 사용법: 컨텍스트 파일 생성
다음 방법을 사용하여 활성 컨텍스트에서 새로운 `orbitron.md` 파일을 빠르게 생성할 수 있습니다:
1. **`Ctrl + K`를 누르거나** `/context`를 입력하여 컨텍스트 선택 패널을 엽니다.
2. **Orbitron Context Manager**에서 원하는 컨텍스트를 선택합니다.
3. Orbitron이 선택된 메모리로 `orbitron.md` 파일을 생성하거나 업데이트합니다.
> 💡 생성된 후에는 모든 후속 명령과 대화가 선택된 컨텍스트를 자동으로 참조합니다.
***
#### 🔍 컨텍스트 관리 명령어
Orbitron은 저장된 대화 또는 프로젝트 컨텍스트를 보기, 필터링 및 관리하는 데 도움이 되는 여러 CLI 명령어를 제공합니다. 이러한 컨텍스트는 AI의 메모리 앵커 역할을 하여 맞춤형, 컨텍스트 인식 지원을 제공할 수 있게 합니다.
| 명령어 | 설명 | 사용 예시 |
| ------------------------------ | ---------------------- | --------------------------------------------------------------------------------------------- |
| `/context` | 사용 가능한 컨텍스트 전체 확인 | `/context` |
| `/context:tag [tag]` | 특정 태그와 연결된 컨텍스트만 표시 |
/context:tag cloud
/context:tag security
|
| `/context:category [category]` | 특정 카테고리 컨텍스트를 필터링하여 표시 |
/context:category production
/context:category staging
|
#### `/context:tag [tag]`
* 특정 주제와 관련된 컨텍스트를 빠르게 검색하고 싶을 때 사용하세요 (예: `aws`, `devops`, `cost-optimization`).
#### `/context:category [category]`
* 카테고리는 `development`, `production`, `experiments` 등과 같은 논리적 그룹을 나타낼 수 있습니다.
이러한 명령어는 쿼리에 응답할 때 Orbitron이 사용하는 컨텍스트 메모리의 범위를 좁히는 데 도움이 됩니다. 선택되면 연결된 메모리가 현재 세션에 로드됩니다.
***
#### ✅ 컨텍스트 인식 상호작용의 장점
* **지속적 메모리**: 컨텍스트가 세션 간에 저장됨
* **정확한 응답**: AI가 프로젝트별 정보를 기반으로 답변을 맞춤화할 수 있음
* **편집 가능**: 사용자가 `orbitron.md`에서 컨텍스트를 수동으로 업데이트할 수 있음
* **다중 컨텍스트 지원**: 매니저를 사용하여 필요에 따라 컨텍스트 간 전환 가능
> 💡 팁: 여러 프로젝트를 동시에 진행할 때, 각 프로젝트별 `orbitron.md`를 관리하면 효율적입니다.
***
### ⛓️💥 3. **비대화형 모드**
Orbitron은 자동화, 스크립팅 또는 최소한의 UI 상호작용을 선호하는 사용자를 위해 **비대화형 모드**를 지원합니다.
이 모드에서는 대화형 터미널 세션에 들어가지 않고도 CLI를 통해 직접 질문이나 명령을 입력하고 즉시 응답을 받을 수 있습니다.
* 모든 필수 옵션은 CLI 플래그나 구성 파일을 통해 전달되어야 함
* 완전한 자동화 및 배치 처리 가능
* 헤드리스 환경 및 파이프라인에 이상적
#### 🛠 사용 방법
`-p` (prompt) 플래그 뒤에 질문이나 명령을 입력하여 Orbitron을 비대화형으로 호출할 수 있습니다:
**🔹 기본 실행**
```bash
orbitron -p "모든 EC2 인스턴스를 나열하는 방법은?"
```
이는 질문을 AI 엔진에 전송하고 응답을 표준 출력으로 인쇄합니다.
**🔹 조용 모드 (깔끔한 출력)**
```bash
orbitron -p "모든 EC2 인스턴스를 나열하는 방법은?" -q
```
이는 타임스탬프, 헤더 또는 진행률 표시기와 같은 메타 정보를 숨겨 더 깔끔한 응답을 제공합니다 — 파이핑이나 로깅에 이상적입니다.
**🔹 JSON 형식 출력**
```bash
orbitron -p "모든 EC2 인스턴스를 나열하는 방법은?" -q -f json
```
이는 AI 응답을 구조화된 JSON 객체로 래핑하여 반환하며, 프로그래밍 방식의 파싱이나 통합에 적합합니다.
***
#### 📤 지원되는 출력 형식
| 형식 | 설명 |
| ------ | ---------------------- |
| `text` | 일반 텍스트 출력 (기본값) |
| `json` | 구조화된 필드를 가진 JSON 래핑 출력 |
> 💡`-f text` 또는 `-f json`을 사용하여 출력 형식을 지정할 수 있습니다.
***
#### ✅ 사용 사례 예시
* **셸 스크립팅**:
```bash
orbitron -p "S3 버킷을 백업하는 bash 스크립트 생성" -q > backup.sh
```
* **CI/CD 통합**:
```bash
orbitron -p "terraform plan 출력 요약" -q -f json | jq '.response'
```
* **채팅 없는 자동화**: `-q`와 `-f`를 함께 사용하여 관련 정보만 추출하고 모든 UI/UX 프롬프트를 숨깁니다.
***
### 🚩 명령줄 플래그
다음 플래그들은 **Orbitron을 비대화형 모드에서 사용**할 때 사용할 수 있습니다. 이러한 옵션을 통해 실행 동작을 사용자 정의하고, 출력을 제어하며, Orbitron을 스크립트나 자동화 파이프라인에 통합할 수 있습니다.
플래그
별칭
타입
설명
--cwd
-c
string
현재 작업 디렉토리를 설정합니다. 상대 경로 해결 또는 프로젝트별 명령 실행에 유용합니다.
--debug
-d
boolean
문제 해결을 위한 자세한 출력이 포함된 디버그 모드를 활성화합니다.
--help
-h
boolean
도움말 정보와 사용 지침을 표시합니다.
--output-format
-f
string
출력 형식을 지정합니다: text (기본값) 또는 json.
--prompt
-p
string
비대화형 모드에서 단일 프롬프트를 실행합니다.
--quiet
-q
boolean
스피너 및 추가 터미널 UI 요소를 숨깁니다. 깔끔하거나 기계 판독 가능한 출력에 이상적입니다.
--version
-v
boolean
Orbitron의 현재 버전을 표시합니다.
--access-token
string
프로그래밍 방식 인증을 위한 액세스 토큰입니다. --refresh-token과 함께 사용해야 합니다.
--refresh-token
string
프로그래밍 방식 인증을 위한 리프레시 토큰입니다. --access-token과 함께 사용해야 합니다.
#### ✅ 사용 예시
**📋 기본 프롬프트**
```bash
orbitron -p "최신 Terraform 계획 요약"
```
**🧼 깔끔한 출력 (조용 모드)**
```bash
orbitron -p "모든 S3 버킷 나열" -q
```
**🧾 자동화용 JSON 출력**
```bash
orbitron -p "GCP 청구 확인" -q -f json
```
**📁 사용자 정의 작업 디렉토리**
```bash
orbitron -p "이 디렉토리에서 시크릿 스캔" -c ./infra/
```
**🐞 디버깅 활성화**
```bash
orbitron -p "내 ECS 배포 진단" -d
```
> ℹ️ 팁: CI/CD 파이프라인이나 스크립트 워크플로에서 완전한 제어를 위해 여러 플래그를 결합할 수 있습니다.
***
### 🎯 요약
| 모드 | 설명 | 사용 사례 |
| ---------------- | ------------------------------------------------------ | ----------------------------------- |
| **대화형 모드** | 실시간 AI 상호작용이 있는 터미널 세션을 시작합니다. | 처음 사용하는 사용자, 탐색적 작업, 수동 프롬프트 |
| **컨텍스트가 있는 대화형** | 컨텍스트 인식 응답을 위해 프로젝트 메모리(`orbitron.md`)가 로드된 대화형 세션입니다. | 진행 중인 프로젝트, 구조화된 워크플로, 어시스턴트 주도 자동화 |
| **비대화형 모드** | CLI를 통해 단일 명령 또는 질문을 실행하고 즉시 출력을 반환합니다. | 자동화 스크립트, CI/CD 파이프라인, 빠른 일회성 쿼리 |
***
#### ⚠️ 주의사항
* `orbitron.md`는 중요한 컨텍스트 정보를 담고 있으므로, 실수로 삭제하거나 변경하지 않도록 주의해야합니다.
* 비대화형 모드에서는 모든 옵션을 정확히 지정해야 하며, 오타나 누락 시 오류 발생 가능성이 있습니다.
* 여러 컨텍스트를 사용할 경우, 항상 현재 로드된 컨텍스트를 확인 후 작업해야합니다.