✦✧ upstage-cli

English docs: README.en.md

upstage-cli는 Upstage Solar Pro4 기반 에이전트형 터미널 UI(TUI)입니다. Bun 위에서 네이티브로 렌더링되는 OpenTUI, 내장 도구 36개, MCP 클라이언트/서버 연동, 평가 하네스(harness)를 갖췄습니다. 모델별 기능 테이블을 통해 solar-pro3/solar-pro2도 지원합니다.

독립 실행형 바이너리 (macOS/Linux) — Node나 Bun 설치 없이 바로 사용:

curl -fsSL https://raw.githubusercontent.com/VectorSophie/upstage-cli/master/scripts/install.sh | bash

최신 릴리스에서 플랫폼에 맞는 upstage-<platform>-<arch> 빌드를 내려받아 ~/.local/bin에 설치합니다. Windows: 릴리스 페이지에서 upstage-windows-x64.zip을 내려받아 upstage.exe를 직접 실행하세요.

npm (이미 Node를 쓰고 있고 Bun을 따로 설치해도 괜찮다면):

npm install -g @jackochesstern/upstage-cli

PATH에 Bun 1.3 이상이 필요합니다 (TUI가 Bun 전용 네이티브 렌더러 위에서 동작합니다) — 위 독립 실행형 바이너리는 Bun 런타임이 바이너리 안에 이미 컴파일되어 있어 이 요구사항이 없습니다.

export UPSTAGE_API_KEY=your_key   # console.upstage.ai 에서 발급

upstage                            # 대화형 TUI 실행
upstage -p "실패하는 테스트 고쳐줘"  # 단발 프롬프트 후 종료
upstage ask "package.json 요약해줘"

아래 명령으로 저장소를 준비하고 실행할 수 있습니다.

bun install
bun start

upstage-cli 실행에 중요한 환경 변수는 다음과 같습니다.

루트 디렉터리에 .env 파일을 두고 관리할 수 있습니다. 전체 UPSTAGE_* 환경 변수 목록(재시도/타임아웃/로깅/압축 등, 약 27개)은 src/config/env.mjs의 ENV_SCHEMA를 참고하세요.

upstage --help가 항상 최신 기준입니다. 현재 기준 전체 옵션:

Usage: upstage [command] [options] [prompt]

Commands:
  chat              풀스크린 TUI 실행 (기본값 — 명령어 없이 실행한 것과 동일,
                    "tui"와도 동일)
  tui               풀스크린 TUI 실행 ("chat" / 명령어 없음과 동일)
  ask               단발 프롬프트 모드 — TUI 없이 헤드리스로 실행 후 종료

  "chat", "tui", 그리고 명령어 없이 실행하는 것은 서로 다른 모드가 아니라
  동일한 풀스크린 TUI를 가리키는 세 가지 이름입니다. "ask"(또는 프롬프트/-p
  전달)만 실제로 다른, 비대화형 모드입니다.

Options:
  -h, --help                도움말 표시
  -p, --prompt <text>       프롬프트 실행 후 종료
  -m, --model <model>       사용할 모델 (기본값 solar-pro4)
  --no-stream               스트리밍 비활성화
  --session <id>            세션 ID로 재개
  --new-session             새 세션 시작
  --reset-session           세션 초기화 후 재생성
  --confirm-patches         패치 적용 전 확인 요구
  --bridge-json             JSON 브리지 형식으로 출력
  --permission-mode <mode>  권한 모드
  --system-prompt <text>    시스템 프롬프트 재정의
  --cwd <dir>                이 디렉터리에서 실행한 것처럼 동작 (다른 무엇보다
                            먼저 process cwd를 변경)
  --add-dir <dir>           UPSTAGE.md 탐색 추가 디렉터리
  --max-turns <n>           최대 대화 턴 수
  --max-time <sec>          최대 실행 시간(초) (기본값 180)
  --allowedTools <tools>    허용 도구 목록(쉼표 구분)
  --disallowedTools <tools> 차단 도구 목록(쉼표 구분)
  --lang <code>             언어 (ko/en)
  -v, --verbose             상세 출력
  -d, --debug               디버그 모드

upstage-cli 인터페이스는 두 영역으로 구성됩니다.

1. 채팅(왼쪽 패널): 요청 입력, 에이전트 응답 확인, 패치/디프 미리보기
2. 사이드바(오른쪽 패널): 작업 맥락과 상태 정보
   • Plan: 현재 작업을 원자적 단계로 분해한 계획
   • Context: 저장소 맵과 현재 맥락에 포함된 파일
   • Tools: 최근 도구 실행 및 관찰 결과

복잡한 요청은 실행 전에 Plan 모드를 거칩니다. 에이전트가 문제를 단계별로 분해하고, 사이드바의 Plan 탭에서 진행 상황을 추적할 수 있습니다. 이 흐름은 작업의 투명성과 예측 가능성을 높입니다.

upstage-cli는 경로 범위 기반 쓰기 보호 정책을 적용합니다. 기본적으로 에이전트는 현재 작업 디렉터리(process.cwd()) 내부만 수정할 수 있습니다.

• 제한된 쓰기: 신뢰 경로 밖 파일 수정은 차단되며, SECURITY_OVERRIDE=true일 때만 허용
• 확인 절차: 셸 실행, 파일 쓰기 같은 고위험 작업은 상호작용 확인 절차를 통해 승인

총 36개 명령어입니다. 앱 안에서 /help를 입력하면 현재 목록을 볼 수 있습니다. 용도별로 묶으면:

파일 입출력: read_file, write_file, edit_file, multi_edit, delete_file, rename_file, create_patch/apply_patch

검색 & 탐색: glob, grep, search_code, semantic_search (Solar의 한국어 최적화 임베딩 기반 관련도 랭킹), list_files, repo_map

인텔리전스 (tree-sitter): find_symbol, find_references, list_modules, index_health

실행: run_shell, run_tests, run_linter, run_typecheck, run_verification

웹: web_fetch, web_search (Tavily 연동, TAVILY_API_KEY 필요)

GitHub: gh_issue_read, gh_issue_comment, gh_pr_create, gh_pr_review

Document AI & 검증: read_document (스캔/촬영된 PDF·이미지 OCR + 레이아웃 분석, Upstage Document AI), check_groundedness (주장이 실제 근거 컨텍스트에 부합하는지 검증, Upstage Groundedness Check API)

스킬 & 작업 관리: load_skill, todo_read/todo_write

메타: run_subagent (범위가 제한된 서브에이전트 실행, 격리된 git worktree 옵션 지원), echo

Discovery 도구 등록/실행 예시:

UPSTAGE_DISCOVERY_COMMAND="node tools/discovery-bridge.mjs discover"
UPSTAGE_DISCOVERY_INVOKE_COMMAND="node tools/discovery-bridge.mjs invoke"

discover 명령은 다음 형태의 JSON 배열을 출력해야 합니다.

[
  {
    "name": "project_lint",
    "description": "Run project lint",
    "risk": "medium",
    "actionClass": "exec",
    "inputSchema": {
      "type": "object",
      "properties": {},
      "additionalProperties": false
    }
  }
]

MCP 서버 모듈 로딩 예시:

UPSTAGE_MCP_SERVERS_MODULE=./tools/mcp-servers.mjs

export default [
  {
    name: "repo",
    client: {
      async listTools() {
        return [];
      },
      async callTool(toolName, args, context) {
        return { toolName, args, context };
      }
    }
  }
];

프로젝트 루트에 .mcp.json 을 두면 실제 MCP 서버를 자동으로 연결합니다. stdio 와 Streamable HTTP 두 전송을 모두 지원하며, 표준 JSON-RPC 2.0 로 tools/list · tools/call 을 수행하고, 등록된 도구는 <서버이름>__<도구이름> 으로 노출됩니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "remote-api": {
      "url": "https://your-host.example.com/mcp",
      "headers": { "Authorization": "Bearer ..." }
    }
  }
}

• command → stdio 전송, url → Streamable HTTP 전송(세션·SSE 응답 처리 포함).
• settings.json 의 mcpServers 와 병합되며, 연결 실패한 서버는 경고 후 건너뜁니다.

어느 디렉터리에든 UPSTAGE.md를 두면 해당 디렉터리(또는 하위 디렉터리)에서 에이전트가 실행될 때 시스템 프롬프트에 자동으로 병합됩니다 (Claude의 CLAUDE.md와 유사). UPSTAGE.md가 없는 디렉터리에서는 여러 에이전트 도구가 함께 쓰는 AGENTS.md 규약으로 대체 탐색합니다.

아래 순서대로 실행하면 주요 기능을 빠르게 검증할 수 있습니다.

npm run check
npm test

upstage ask -p "현재 디렉터리 파일 목록을 간단히 정리해줘"
upstage ask -p "src/agent/loop.mjs 구조를 설명해줘" --no-stream

확인 포인트:

• 응답이 정상 출력되는지
• --no-stream에서 토큰 스트리밍 없이 완료 응답이 오는지

upstage ask -p "README 파일 이름을 알려줘" --bridge-json

확인 포인트:

• stdout이 JSON line 이벤트(token, event, result)로 출력되는지
• 자동화 스크립트에서 파싱 가능한지

upstage --new-session
upstage --session <session-id>
upstage --reset-session --session <session-id>

확인 포인트:

• 새 세션 생성/재개/초기화가 정상 동작하는지
• 세션 브라우저(/sessions)에서 최근 세션 목록이 보이는지

upstage ask -p "작은 텍스트 파일을 하나 생성해줘" --confirm-patches

확인 포인트:

• 고위험 작업 전에 승인 프롬프트가 뜨는지
• 거부 시 작업이 차단되는지

UPSTAGE_VERIFY_STAGES=run_linter,run_tests upstage ask -p "아주 작은 코드 변경을 적용해줘" --confirm-patches

확인 포인트:

• 검증 로그에서 지정한 단계만 실행되는지

1. UPSTAGE_DISCOVERY_COMMAND/UPSTAGE_DISCOVERY_INVOKE_COMMAND 또는 UPSTAGE_MCP_SERVERS_MODULE 설정
2. upstage 실행 후 도구 목록(/tools) 또는 실제 요청으로 확장 도구 호출

확인 포인트:

• 확장 도구가 등록되어 노출되는지
• 호출 시 JSON 결과가 정상 관찰되는지

MIT © VectorSophie