dbxcli: 명령줄에서 사용하는 Dropbox

Scorecard

CodeQL

Release

dbxcli는 파일, 공유 링크, 팀 및 자동화 워크플로우를 위한 스크립트 가능한 Dropbox CLI입니다. 이는 터미널의 사용자, 스크립트, CI 작업, 에이전트 스타일 워크플로우를 위해 구축되었습니다.

dbxcli 사용 이유?

• 터미널에서 Dropbox 작업하기
• 파일, 폴더 및 스트림 업로드 및 다운로드
• 공유 링크 생성, 검사, 업데이트, 취소 및 다운로드
• 스크립트 및 자동화를 위해 JSON 출력 사용
• 생성된 콘텐츠를 Dropbox로 직접 파이프하기
• 멤버 범위 접근을 사용하여 팀 워크플로우 관리

빠른 시작

dbxcli login
dbxcli ls /
dbxcli put local.txt /remote.txt
...

/가 쓰기 가능한 공간이 아닌 팀 계정의 경우, dbxcli ls /를 실행하고 대신 쓰기 가능한 개인 또는 팀 폴더를 사용하십시오.

자동화를 위해서는 구조화된 명령어 출력과 JSON 도움말 검색 기능을 사용하십시오:

dbxcli ls --output=json /
dbxcli --help --output=json
dbxcli put --help --output=json

안정적인 JSON 래퍼(envelopes), 오류 코드 및 프로세스 종료 코드는 Automation and JSON output에서 문서화되어 있습니다.

JSON 출력

구조화된 실행 출력을 지원하는 명령어의 경우, --output=json을 사용하면 명령어를 실행하고 자동화를 위해 안정적인 스키마 v1 성공 및 오류 래퍼를 방출합니다.

JSON 도움말은 기계가 읽을 수 있는 명령어 검색 표면(command-discovery surface)입니다. 이를 사용하여 명령어 경로, 인수, 플래그, 별칭, 입력 스키마, 인증 동작, stdin/stdout 동작, 스키마 참조 및 구조화된 명령어 실행 출력이 지원되는지 여부를 검색할 수 있습니다:

dbxcli --help --output=json
dbxcli put --help --output=json

스키마는 JSON schema v1 docs에서 확인하고, 안정성 정책(stability policy), 명령어 계약(command contracts), 예시를 참고하세요.

일반적인 워크플로우 (Common workflows)

파일 업로드:

dbxcli put report.pdf /Reports/report.pdf

덮어쓰지 않고 업로드:

dbxcli put --if-exists fail report.md /Reports/report.md

파이프를 통해 업로드:

tar cz ./project | dbxcli put - /Backups/project.tgz

stdout으로 다운로드:

dbxcli get /Backups/project.tgz - | tar tz

공유 링크 생성:

dbxcli share-link create /Reports/report.pdf

텍스트 모드에서 share-link create는 공유 링크 URL만 stdout에 출력합니다:

url="$(dbxcli share-link create /Reports/report.pdf)"

문제 해결 (Troubleshooting)

팀 계정에서 /remote.txt로 업로드 실패 원인은 무엇인가요?

일부 팀 계정은 쓰기 가능한 Dropbox 루트 네임스페이스(writable Dropbox root namespace)를 가지고 있지 않을 수 있습니다. 먼저 dbxcli ls /을 실행한 다음, 개인 폴더나 팀 폴더와 같이 쓰기가 가능한 폴더 아래에 업로드하세요.

프록시 설정 (Proxy configuration)

dbxcli는 Go의 표준 HTTP 프록시 동작(standard HTTP proxy behavior)을 사용하므로, HTTPS_PROXY, HTTP_PROXY, 그리고 NO_PROXY가 Dropbox API 요청 및 CLI에서 수행하는 OAuth 토큰 교환/갱신 요청에 적용됩니다.

Dropbox API 및 OAuth 요청의 경우, HTTPS_PROXY를 설정하세요:

HTTPS_PROXY=http://127.0.0.1:8080 dbxcli ls /

셸 세션(shell session)의 경우:

export HTTPS_PROXY=http://proxy.company.example:8080
export NO_PROXY=localhost,127.0.0.1,.company.example
dbxcli login

Windows PowerShell의 경우:

$env:HTTPS_PROXY = "http://127.0.0.1:8080"
dbxcli login

Windows cmd의 경우:

set HTTPS_PROXY=http://127.0.0.1:8080
dbxcli login

HTTP_PROXY도 일반 HTTP 요청에 대해 인식됩니다(is also honored). NO_PROXY를 사용하여 로컬 또는 내부 호스트에 대한 프록시 우회(bypass)가 가능합니다. 또한, 소문자 형태인 https_proxy와 no_proxy도 Go의 HTTP 스택에서 지원됩니다.

프록시에 기본 인증(basic authentication)이 필요한 경우, 자격 증명(credentials)을 프록시 URL에 포함시키세요:

HTTPS_PROXY=http://user:[email protected]:8080 dbxcli ls /

프록시 사용자 이름이나 비밀번호에 URL-encoding을 적용하세요. 환경 변수, 셸 히스토리, CI 로그 및 프로세스 목록에서 프록시 자격 증명(credentials) 관리에 주의하십시오.

dbxcli login의 브라우저 인증 단계는 dbxcli 외부에서 이루어집니다. 해당 페이지 역시 프록시가 필요하다면, 브라우저나 운영 체제 수준에서 별도로 구성해야 합니다.

기능 (Features)

• 파일 작업: ls, cp, mkdir, mv, rm, put, 및 get
• put -r 및 get -r을 사용한 재귀적 업로드 및 다운로드
• stdin 업로드와 stdout 다운로드를 통한 파이프 친화적인 전송(Pipe-friendly transfers)
• put --if-exists overwrite|skip|autorename|fail 및 cp/mv --if-exists fail|skip|autorename을 사용한 충돌 제어
• 공유 링크 생성, 목록 보기, 검사, 업데이트, 취소 및 다운로드
• 검색, 파일 개정판(revisions), 복원, 유연한 정렬, 시간 형식 지정
• 대용량 파일을 위한 청크 업로드(Chunked uploads) 및 대용량 디렉터리를 위한 페이지네이션 목록 보기
• 갱신 가능한 저장 자격 증명(refreshable saved credentials)을 사용한 OAuth 로그인
• DBXCLI_ACCESS_TOKEN을 이용한 직접 토큰 자동화
• DBXCLI_AUTH_FILE을 이용한 대체 저장 자격 증명 파일
• 지원되는 명령에 대한 구조화된 JSON 성공 및 오류 엔벨로프(envelopes)
• 기계가 읽기 쉬운 명령어 검색을 위한 JSON 도움말 매니페스트(manifests)
• 팀 관리 명령어 및 --as-member를 사용한 멤버 범위 접근

설치 (Installation)

Homebrew

brew install dbxcli

Homebrew 포뮬러: formulae.brew.sh/formula/dbxcli

WinGet

winget install --exact --id Dropbox.dbxcli

WinGet 매니페스트: microsoft/winget-pkgs

릴리스 아카이브 (Release archives)

releases 페이지에서 사용자의 플랫폼에 맞는 아카이브를 다운로드하고, 체크섬을 확인한 후, dbxcli 바이너리를 PATH의 어딘가에 설치하십시오.

Linux 예시:

Release assets에는 다음이 포함됩니다:

• dbxcli_X.Y.Z_darwin_amd64.tar.gz
• dbxcli_X.Y.Z_darwin_arm64.tar.gz
• dbxcli_X.Y.Z_linux_amd64.tar.gz
• dbxcli_X.Y.Z_linux_arm64.tar.gz
• dbxcli_X.Y.Z_linux_arm.tar.gz
• dbxcli_X.Y.Z_openbsd_amd64.tar.gz
• dbxcli_X.Y.Z_windows_amd64.zip
• SHA256SUMS

소스에서 빌드하기

go install github.com/dropbox/dbxcli/v3@latest

또는 클론하여 빌드하기:

git clone https://github.com/dropbox/dbxcli.git
cd dbxcli
go build .

Claude Code 플러그인

/plugin marketplace add Dropbox/dbxcli
/plugin install dbxcli@dbxcli

그런 다음 /dbxcli 스킬을 사용하여 Claude Code에서 Dropbox와 연동하여 작업합니다.

Codex 스킬

Codex에서 프로젝트 스킬로 dbxcli를 사용하려면, 표준화된(canonical) 스킬을 리포지토리의 .codex 디렉터리로 복사합니다:

mkdir -p .codex/skills
cp -R skills/dbxcli .codex/skills/dbxcli

새로운 Codex 작업을 시작한 다음, $dbxcli를 호출하여 로컬 CLI를 통해 Dropbox와 작업합니다.

지원 현황(Support posture)

dbxcli는 Dropbox 엔지니어들에 의해 Dropbox GitHub 조직에서 유지 관리되지만, 공식적으로 지원되는 Dropbox 제품은 아닙니다. 버그 및 기여에 대해서는 GitHub 이슈와 풀 리퀘스트를 사용하십시오. Dropbox Support는 이 CLI에 대한 지원을 제공하지 않습니다. 이 CLI는 전체 API 표면(full API surface)이 아닌, 실용적인 부분 집합(practical subset)의 Dropbox API 기능을 구현합니다.

명령어 참조(Command reference)

완전한 생성된 명령어 참조는 다음에서 확인할 수 있습니다:

• dbxcli 명령어 참조

특정 명령어 도움말을 받으려면 다음을 실행하십시오:

dbxcli --help
dbxcli put --help
dbxcli share-link --help
...

기계가 읽을 수 있는 명령어 검색(machine-readable command discovery)을 사용하려면 JSON 도움말을 사용하십시오:

dbxcli --help --output=json
dbxcli put --help --output=json

문서

• 자동화 및 JSON 출력
• 공유 워크플로우
• JSON 스키마 v1
• 릴리스 기록
• 기여하기

Generated Cobra 명령줄 문서가 docs/commands/ 아래에 생생하게 존재하며, CI는 이들이 CLI와 동기화되는지 확인합니다.

기여하기

기여를 환영합니다. 개발 환경 설정, 테스트, 풀 리퀘스트 가이드라인 및 Dropbox Contributor License Agreement는 CONTRIBUTING.md를 참조하세요.

유용한 자료

• Dropbox Go SDK
• Dropbox API 문서