atlassian-cli
Jira, Confluence, Bitbucket 및 JSM을 위한 통합 CLI
터미널에서 전체 Atlassian Cloud 스택을 자동화할 수 있습니다. 대량 작업(Bulk operations), 드라이-런 모드(dry-run mode), 다중 출력 형식 (JSON/CSV/YAML/table), 프로필 기반의 다중 인스턴스 지원 기능을 제공합니다.
독립적인 오픈 소스 프로젝트입니다. atlassian-cli는 자체 공식 CLI (acli)와 관련이 없습니다. Atlassian, Jira, Confluence, Bitbucket 및 Jira Service Management는 Atlassian Pty Ltd의 상표이며, 제품명은 여기에서 호환성을 식별하기 위해서만 사용됩니다.
CI
crates.io
MIT License
문서 및 가이드 (Documentation & guides)
전체 문서, 명령어 참조, 사용 설명서는 프로젝트 사이트에서 확인할 수 있습니다:
- Jira 가이드: 이슈(issues), 프로젝트(projects), 대량 작업(bulk operations), 워크플로우(workflows)
- Confluence 가이드: 스페이스(spaces), 페이지(pages), 블로그 게시물(blog posts), 첨부 파일(attachments)
- Bitbucket 가이드: 리포지토리(repos), 브랜치(branches), 풀 리퀘스트(pull requests), 파이프라인(pipelines)
- Jira Service Management 가이드: 서비스 데스크 및 요청(service desks and requests)
- 설치 가이드: Homebrew, Cargo 및 사전 구축된 바이너리
- 블로그: 릴리스 노트(release notes), 팁, 워크플로우 레시피
설치 (Installation)
Homebrew (macOS/Linux)
brew tap omar16100/atlassian-cli
...
Homebrew의 최신 버전은 사용자가 신뢰하지 않는(untrusted) 외부 tap에서 포뮬러를 로드하는 것을 거부합니다. Homebrew가 "Refusing to load formula ... from untrusted tap"라고 보고하면, 해당 tap을 신뢰한 후 설치 또는 업그레이드를 진행하십시오:
brew trust omar16100/atlassian-cli
brew upgrade atlassian-cli
Cargo (crates.io에서)
cargo install atlassian-cli
소스 코드로부터 (From Source)
git clone https://github.com/omar16100/atlassian-cli
cd atlassian-cli
cargo install --path crates/cli
사전 빌드 바이너리 (Pre-built Binaries)
플랫폼별 최신 릴리스는 Releases 페이지에서 다운로드하세요.
바이너리는 macOS(Apple Silicon 및 Intel)와 Linux x86_64(glibc 및 musl)용으로 빌드되었으며, dist-workspace.toml에서 targets를 확인하세요. Windows 바이너리는 없습니다.
프로젝트 레이아웃 (Project Layout)
crates/
cli/ # Clap 기반 바이너리 진입점(binary entry point)
api/ # 경량 HTTP 클라이언트 래퍼 (reqwest)
...
시작하기 (Getting Started)
- Rust 툴체인(rustup)을 설치하고
cargo가 PATH에 있는지 확인합니다.
- 종속성을 가져오고 워크스페이스 컴파일을 확인합니다:
cargo check
3. `atlassian-cli` 바이너리가 사용 가능하도록 CLI를 로컬에 설치합니다 (`~/.cargo/bin`이 PATH에 있는지 확인하세요):
```bash
cargo install --path crates/cli
- CLI 도움말을 실행하여 현재 서브커맨드를 검사합니다:
atlassian-cli --help
atlassian-cli jira --help
atlassian-cli confluence --help
...
5. 프로필과 API 토큰을 추가합니다:
```bash
atlassian-cli auth login \
--profile personal \
--base-url https://example.atlassian.net
... ```
6. 구성된 프로필 목록을 나열합니다 (존재하는 경우 `~/.config/atlassian-cli/config.yaml`을 읽습니다):
```bash
atlassian-cli auth list
팁: 로그인 명령 실행 전에 시작점으로 cp configs/config.example.yaml ~/.config/atlassian-cli/config.yaml를 사용하세요.
7. Jira, Confluence, Bitbucket 및 JSM 명령을 시도합니다 (실제 데이터 필요):
atlassian-cli jira issue search --jql "project = DEV order by created desc" --limit 5
atlassian-cli jira issue get DEV-123
...
구성 위치 (Configuration Location)
config.yaml과 암호화된 자격 증명은 이 순서로 선택된 하나의 디렉터리에 저장됩니다:
$ATLASSIAN_CLI_CONFIG_DIR, 또는 --config-dir$XDG_CONFIG_HOME/atlassian-cli~/.config/atlassian-cli~/.atlassian-cli (또는 이전 버전인 ~/.atlcli) — 이 중 어느 것이 여전히 파일들을 가지고 있는지에 따라 다름
macOS와 Linux에서는 ~/.config를 사용합니다. Windows의 기본 경로는 %LOCALAPPDATA%\atlassian-cli입니다.
export ATLASSIAN_CLI_CONFIG_DIR=/tmp/ci-atlassian
atlassian-cli --config-dir ./scratch auth list
...
상대 경로의 $XDG_CONFIG_HOME은 XDG base directory spec에 따라 무시됩니다. 반면, 상대 경로의 $ATLASSIAN_CLI_CONFIG_DIR는 이 도구 자체의 변수이므로 존중받으며, ./ci-config는 고정된 작업 디렉토리를 가진 Job에서 작성하기에 합리적인 이름입니다.
~/.atlassian-cli에서 마이그레이션하는 방법
기존 설치본은 명령어를 실행할 때 처음으로 이동됩니다. 파일들은 새 위치로 복사되고 이전 디렉토리는 ~/.atlassian-cli.migrated로 이름이 변경됩니다. 아무것도 삭제되지 않으며, 무엇이 어디로 갔는지 안내받게 됩니다. 이 이름 변경은 의도적인 것입니다. 조용히 무시되는 남아있는 사본(lingering copy)은 함정일 수 있기 때문입니다. 왜냐하면 나중에 그곳을 편집하더라도 아무런 효과가 없기 때문입니다.
$ATLASSIAN_CLI_CONFIG_DIR를 설정하면 이동 과정 자체가 완전히 건너뜁니다. 이는 명시적인 선택이 전적으로 신뢰된다는 의미입니다.
Unix 시스템에서는 디렉토리가 0700 권한으로, 두 파일은 0600 권한으로 생성됩니다.
명령어 별칭 (Command Aliases)
편의를 위해 다음 명령어 별칭이 사용 가능합니다:
| 전체 명령어 | 별칭 | 설명 |
|---|
bitbucket | bb | Bitbucket 명령어 |
사용 예시:
atlassian-cli bitbucket pipeline list --workspace myworkspace
...
Bitbucket 인증 (Bitbucket Authentication)
Bitbucket은 Jira/Confluence와는 별도의 범위 지정(scoped) API 토큰을 요구합니다.
왜 별도의 토큰이 필요한가요?
| 제품 | 토큰 유형 | 생성 방법 |
|---|
| Jira/Confluence | 일반 API 토큰 (Regular API token) | "API 토큰 생성(Create API token)" |
| Bitbucket | 범위 지정 API 토큰 (Scoped API token) | "범위가 있는 API 토큰으로 생성(Create API token with scopes)" → Bitbucket 선택 |
Atlassian은 범위가 지정된(scoped) API 토큰을 선호하며 Bitbucket 앱 비밀번호를 사용 중단했습니다. 이 토큰들은 명시적인 권한 범위를 가지고 Bitbucket 전용으로 생성되어야 합니다.
Bitbucket 토큰 생성하기
- https://id.atlassian.com/manage-profile/security/api-tokens 로 이동합니다.
- "Create API token with scopes" (일반 "Create API token"이 아님)을 클릭합니다.
- 앱으로 Bitbucket을 선택합니다.
- 필요한 권한 범위(scope)를 추가합니다:
read:repository:bitbucket - 리포지토리 목록/보기write:repository:bitbucket - 리포지토리 생성/업데이트read:pullrequest:bitbucket - PR 보기admin:repository:bitbucket - 관리자 작업
- 토큰을 복사합니다.
참고: Bitbucket의 admin:* 범위에는 read:* 권한이 포함되지 않으므로, 필요하다면 둘 다 추가해야 합니다.
Bitbucket 토큰 설정하기
CLI는 다음 환경 변수들을 순서대로 확인합니다:
| 우선순위 | 변수명 | 설명 |
|---|
| 1 | ATLASSIAN_CLI_BITBUCKET_TOKEN_{PROFILE} | 프로필별 Bitbucket 토큰 |
| ... | | |
export ATLASSIAN_CLI_BITBUCKET_TOKEN_WORK=your-bitbucket-scoped-token
...
만약 Bitbucket 전용 토큰이 발견되지 않으면, 명령어는 일반 ATLASSIAN_CLI_TOKEN_{PROFILE} 토큰으로 대체됩니다.
개발자 워크플로우 (Developer Workflow)
make fmt / make clippy / make test를 사용하여 표준 Rust 툴링 스택(각각 just fmt, just clippy 등에 반영됨)을 이용해 작업 공간을 깔끔하게 유지합니다.make install (또는 just install)은 crates/cli에서 CLI를 컴파일하고 로컬에 설치합니다.
테스트 (Testing)
단위 테스트(Unit tests)는 각 크레이트(crate) 내 코드 옆에 위치합니다. 통합 테스트(Integration tests)는 crates/cli/tests/에서 API 클라이언트와 빌드된 CLI를 사용하며, 대부분은 모의 Atlassian API(wiremock)를 대상으로 합니다.
테스트 실행하기
cargo test --workspace
...
테스트 커버리지 (Test Coverage)
2026년 9월 27일(커밋 e3dc5b1, macOS)에 실행된 cargo test --workspace 결과: 927개 통과, 0개 실패, 1개 무시됨. 무시된 테스트는 실제 credentials.enc 사본을 복호화하는 수동 확인입니다.
| 테스트 대상 | 테스트 수 |
|---|
atlassian-cli 단위 테스트 (crates/cli/src) | 430 |
| ... | |
| 통합 파일에는 Jira (24), Bitbucket (23), Bamboo (22), Confluence (20), Opsgenie (14) 및 JSM (11)에 대한 제품별 스위트가 포함되어 있습니다. | |
CI/CD
GitHub Actions는 모든 풀 리퀘스트(pull request)와 main 브랜치로의 푸시(.github/workflows/) 시 실행됩니다:
ci.yml: Ubuntu 환경에서는 cargo fmt --all -- --check 및 cargo clippy --all-targets --all-features -- -D warnings가, Ubuntu 및 macOS 환경에서는 cargo test --all --no-fail-fast가 실행됩니다.security.yml: 라이선스, 금지 목록(bans), 소스 및 권고 사항에 대한 검사를 수행하는 cargo audit (권고 경고는 작업을 실패시키지 않음)와 cargo deny를 포함하며, 주간 단위로도 실행됩니다.release.yml: 버전 태그가 푸시될 때 cargo-dist가 릴리스 바이너리(macOS 및 Linux)를 빌드하고 Homebrew tap을 업데이트합니다.
Windows는 CI에서 빌드되거나 테스트되지 않습니다.
현재 상태
완료된 기능
Phase 1 - 기반 (Foundation) (100% 완료)
- ✅ 모듈식 크레이트 구조를 갖춘 Cargo 워크스페이스
- ✅ 프로필 지원을 갖춘 설정 로더 (~/.config/atlassian-cli/config.yaml)
- ✅ API 토큰 인증 (이메일+토큰 기본 인증 방식)
- ✅ 재시도, 속도 제한(rate limiting), 페이지네이션 기능이 있는 HTTP 클라이언트
- ✅ 다중 형식 출력 (테이블/JSON/CSV/YAML/조용 모드)
- ✅ 동시성 제어 기능을 갖춘 대량 작업 실행기
- ✅ 모든 크레이트에 대한 단위 테스트
- ✅ GitHub Actions를 사용한 CI/CD
Phase 2 - Jira CLI (100% 완료)
- ✅ 이슈 CRUD 작업 (생성/읽기/업데이트/삭제/검색/전환)
- ✅ 이슈 관리 (할당/해제, 워처(watchers), 링크, 댓글)
- ✅ 프로젝트 수명 주기 (목록 보기/가져오기/생성/업데이트/삭제)
- ✅ 컴포넌트 및 버전 관리
- ✅ 사용자 정의 필드 (목록 보기/가져오기/생성/삭제)
- ✅ 워크플로우 (목록 보기/가져오기/내보내기)
- ✅ 대량 작업 (전환/할당/레이블/내보내기/가져오기)
- ✅ 자동화 규칙 (목록 보기/가져오기/생성/업데이트/활성화/비활성화)
- ✅ 웹훅(Webhooks) (완벽한 CRUD + 테스트)
- ✅ 감사 로그 접근 (목록 보기/내보내기)
- ✅ 역할 관리 (목록 보기/가져오기/액터 추가/액터 제거)
- ✅ API 목킹을 사용한 통합 테스트
Phase 4 - Bitbucket CLI (100% 완료)
- ✅ 레포지토리(Repository) CRUD 작업 (list/get/create/update/delete)
- ✅ 브랜치 관리 (list/get/create/delete/protect/unprotect)
- ✅ 풀 리퀘스트 워크플로우 (list/get/create/update/merge/decline)
- ✅ PR 승인(approvals), 댓글 (최상위 및 인라인), 리뷰어
- ✅ 브랜치 보호 및 제한 설정
- ✅ 워크스페이스 작업 (list/get)
- ✅ 프로젝트 관리 (list/get/create/update/delete)
- ✅ 파이프라인 작업 (list/get/trigger/stop/logs)
- ✅ 웹훅(Webhooks) (list/create/delete)
- ✅ SSH 배포 키 (list/add/delete)
- ✅ 레포지토리 권한 (list/grant/revoke)
- ✅ 커밋 작업 (list/get/diff/browse)
- ✅ 대량 작업:
archive-repos는 오래된(stale) 레포에 대한 이슈 트래커와 위키를 비활성화합니다 (Bitbucket Cloud에는 아카이브 API가 없음). delete-branches는 병합 상태를 확인하지 않고 이름으로 브랜치를 삭제합니다. 둘 다 --execute 플래그가 제공되지 않으면 후보 목록만 보여줍니다.
- ✅ 사용자 정보 (whoami)
- ✅ API 목킹을 사용한 통합 테스트
Phase 3 - Confluence CLI (100% 완료)
- ✅ 스페이스(Space) 작업 (list/get/create/update/delete/permissions)
- ✅ 페이지 관리 (CRUD, 버전, 레이블, 댓글, 제한 설정)
- ✅ 블로그 게시물 (list/get/create/update/delete)
- ✅ 첨부 파일 (list/get/upload/download/delete)
- ✅ 검색 (CQL, 텍스트, 인-스페이스)
- ✅ 대량 작업 (삭제, 레이블 추가, 내보내기(export))
- ✅ 분석 (페이지 조회수, 스페이스 통계)
- ✅ API 목킹을 사용한 통합 테스트
추가 제품 (부분)
- ✅ JSM CLI: 서비스 데스크(service desks), 요청(requests), 큐(queues), 승인(approvals), SLA, 고객(customers), 조직(organizations), 요청 유형(request types), 지식 기반(knowledge base) 및 피드백
- ✅ Opsgenie CLI: 알림(alerts), 인시던트(incidents), 스케줄 및 온콜(schedules and on-call), 팀(teams), 에스컬레이션(escalations), 서비스 및 하트비트(services and heartbeats), 미국(US) 및 유럽(EU) 지역
- ✅ Bamboo CLI: 프로젝트(projects), 플랜(plans), 플랜 브랜치(plan branches), 빌드(builds) (실행/종료(run, stop), 로그(logs), 댓글(comments), 레이블(labels)), 배포(deployments), 에이전트(agents), 아티팩트(artifacts), 서버 정보 및 큐
- Opsgenie와 Bamboo는 모의 API 통합 테스트(mocked-API integration tests)로 커버됩니다 (
crates/cli/tests/opsgenie_integration.rs, bamboo_integration.rs). 세 제품 모두에 대한 나머지 로드맵 항목은 docs/todo.md (Phase 5~7)에 있습니다.
다음 단계
