Ch6. 커스텀 커맨드
.opencode/commands/의 Markdown 커맨드 작성법, $ARGUMENTS·@파일·!셸 변수 참조, opencode run 비대화형 실행과 CI 코드 리뷰 자동화를 정리합니다.
핵심 요약
- 커스텀 커맨드는
.opencode/commands/(프로젝트) 또는~/.config/opencode/commands/(전역)에 Markdown으로 작성하며, frontmatter로agent·model을 지정합니다. - 커맨드 본문에서
$ARGUMENTS·$1/$2로 인수를,@filename으로 파일 내용을,!`command`로 셸 출력을 삽입할 수 있습니다. opencode run "프롬프트"로 비대화형 실행하며--model·--file·--format json·--attach플래그를 조합합니다.opencode run --format json을 GitHub Actions 등 CI 파이프라인에 넣어 PR 코드 리뷰를 자동화할 수 있습니다.- 위험 작업은 읽기 전용 에이전트를, 고비용 작업만 고급 모델을 지정해 사고와 비용을 동시에 줄입니다.
반복 작업을 규칙으로 굳히는 데 커스텀 커맨드만 한 게 없습니다. 프로젝트 표준 커맨드를 미리 만들어두면 신규 멤버 온보딩도 한결 수월합니다.
커스텀 커맨드 작성
파일 위치
| 범위 | 위치 |
|---|---|
| 프로젝트 | .opencode/commands/ |
| 전역 | ~/.config/opencode/commands/ |
커맨드 예시
.opencode/commands/test.md:
---
description: 테스트 실행 후 실패 분석
agent: build
model: anthropic/claude-sonnet-4-5
---
전체 테스트를 실행하고 실패한 테스트의 원인을 분석해주세요.
$ARGUMENTSTUI에서 /test 유닛테스트만으로 실행합니다.
입력 변수와 참조
| 변수 | 설명 | 예시 |
|---|---|---|
$ARGUMENTS | 전체 인수 문자열 | /cmd 전체 인수 |
$1, $2 | 개별 인수 | /cmd 첫번째 두번째 |
@filename | 파일 내용 참조 | @src/index.ts |
!`command` | 셸 출력 삽입 | !`git diff --staged` |
CLI 명령어
대화형 모드 (TUI)
opencode # TUI 시작
opencode [project-path] # 특정 프로젝트에서 시작
opencode --continue # 마지막 세션 이어서
opencode --session [ID] # 특정 세션 재개비대화형 모드
opencode run "프롬프트" # 단일 프롬프트
opencode run --model anthropic/claude-sonnet-4-5 "프롬프트" # 모델 지정
opencode run --file myfile.ts "프롬프트" # 파일 첨부
opencode run --format json "프롬프트" # JSON 출력
opencode run --attach http://localhost:4096 "프롬프트" # 원격 서버 연결관리 명령어
| 명령어 | 설명 |
|---|---|
opencode serve | 헤드리스 서버 시작 (API 접근) |
opencode web | 웹 인터페이스 포함 서버 |
opencode attach [url] | 원격 서버에 TUI 연결 |
opencode agent create | 대화형 에이전트 생성 |
opencode auth login | API 키 설정 |
opencode auth list | 인증 정보 목록 |
opencode models [provider] | 사용 가능한 모델 표시 |
opencode session list | 세션 목록 |
opencode export [sessionID] | 세션을 JSON으로 내보내기 |
opencode import <file> | JSON/공유 URL에서 가져오기 |
opencode upgrade [version] | 업데이트 |
opencode db | 데이터베이스 조회 (v1.2.4+) |
CLI 플래그
| 플래그 | 약어 | 설명 |
|---|---|---|
--model | -m | 모델 지정 (provider/model) |
--file | -f | 파일 첨부 |
--format | 출력 형식 (default, json) | |
--share | 세션 공유 | |
--attach | 실행 중인 서버에 연결 | |
--continue | -c | 마지막 세션 재개 |
--session | -s | 특정 세션 ID 재개 |
고급 팁
- 명령 표준화: 리뷰/테스트/릴리즈용 커맨드를
.opencode/commands/에 팀 공용으로 공유 - 에이전트 지정: 위험 작업은 읽기 전용 에이전트를 지정해 실수 방지
- 모델 지정: 고비용 작업만 고급 모델로 제한하여 비용 절감
- CI 통합:
opencode run으로 CI 파이프라인에서 코드 리뷰 자동화
참고 문서
- 커스텀 커맨드: https://opencode.ai/docs/commands
- CLI 사용법: https://opencode.ai/docs/cli
- 에이전트 설정: https://opencode.ai/docs/agents