1Password CLI(op) 사용법: 터미널에서 비밀번호와 시크릿 관리하기

개발하다 보면 API 키, 데이터베이스 비밀번호, 토큰 같은 시크릿(secret)을 다룰 일이 정말 많죠. .env 파일에 평문으로 저장하자니 불안하고, 팀원이랑 공유하려고 슬랙으로 보내자니 그것도 영 찝찝합니다 😅

1Password는 이미 많은 개발자가 비밀번호 관리 도구로 사용하고 있는데요. 사실 1Password에는 op라는 공식 CLI 도구가 있어서 터미널에서도 1Password 볼트에 저장된 시크릿을 자유롭게 다룰 수 있습니다. 환경 변수에 시크릿을 주입하거나, 스크립트에서 비밀번호를 안전하게 참조하거나, SSH 키 관리까지 가능해요.

이번 글에서는 1Password CLI의 설치부터 실무에서 자주 쓰는 핵심 명령어까지 살펴보겠습니다.

1Password CLI란?

op는 1Password에서 공식으로 제공하는 커맨드라인 도구입니다. 1Password 앱에서 마우스로 하던 작업 대부분을 터미널에서 할 수 있게 해줘요. 비밀번호를 조회하고, 새 항목을 만들고, 볼트를 관리하는 것은 물론이고 개발자에게 특히 유용한 시크릿 참조 기능까지 제공합니다.

1Password 앱을 이미 사용하고 있다면 CLI는 그 연장선에 있는 도구라고 보면 됩니다. 앱에서 저장한 로그인 정보, API 키, 보안 노트 등을 터미널에서 곧바로 꺼내 쓸 수 있으니까요.

설치

운영체제별로 패키지 매니저를 사용해서 설치할 수 있습니다.

macOS에서는 Homebrew로 설치하면 됩니다.

brew install 1password-cli

Windows에서는 winget으로 설치할 수 있습니다.

winget install AgileBits.1Password.CLI

Linux(Debian/Ubuntu)에서는 1Password의 공식 저장소를 추가한 후 apt로 설치합니다.

# 1Password GPG 키 추가
curl -sS https://downloads.1password.com/linux/keys/1password.asc | \
  sudo gpg --dearmor --output /usr/share/keyrings/1password-archive-keyring.gpg

# 저장소 추가
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/1password-archive-keyring.gpg] https://downloads.1password.com/linux/debian/$(dpkg --print-architecture) stable main" | \
  sudo tee /etc/apt/sources.list.d/1password.list

# 설치
sudo apt update && sudo apt install 1password-cli

설치가 완료되면 버전을 확인해볼까요?

op --version

결과

2.30.3

1Password 데스크톱 앱이 설치되어 있다면 앱 연동을 통해 더 편리하게 인증할 수 있습니다. 앱에서 설정 > 개발자 > CLI 통합 활성화를 켜두면 op 명령어를 실행할 때 앱에서 생체 인증(지문이나 얼굴 인식)으로 바로 승인할 수 있거든요. 매번 마스터 비밀번호를 타이핑할 필요가 없어서 훨씬 편합니다.

로그인이 잘 됐는지 확인해봅시다.

op account list

결과

URL                   EMAIL                  USER ID
my.1password.com      dale@example.com       ABCDEFGHIJKLMN

볼트와 항목 조회

1Password에서 볼트(vault)는 시크릿을 담는 폴더 같은 개념입니다. 개인용 볼트, 팀 공유 볼트 등으로 구분해서 관리하는데 CLI에서도 동일하게 접근할 수 있어요.

먼저 접근 가능한 볼트 목록을 확인해보겠습니다.

op vault list

결과

ID                            NAME
xxxxxxxxxxxxxxxxxxxxxxxxxxxx  Personal
yyyyyyyyyyyyyyyyyyyyyyyyyyyy  Development

특정 볼트에 있는 항목들을 조회하려면 op item list를 사용합니다.

op item list --vault Development

결과

ID                            TITLE                 VAULT
aaaaaaaaaaaaaaaaaaaaaaaaaaaa  AWS Access Key        Development
bbbbbbbbbbbbbbbbbbbbbbbbbbbb  Database Password     Development
cccccccccccccccccccccccccccc  GitHub Token          Development

특정 항목의 상세 정보를 보려면 op item get을 사용합니다.

op item get "GitHub Token"

이 명령어는 해당 항목의 모든 필드를 보여주는데요. 특정 필드의 값만 깔끔하게 가져오고 싶다면 --fields 옵션을 쓰면 됩니다.

op item get "GitHub Token" --fields password

이렇게 하면 비밀번호 값만 딱 출력되어서 스크립트에서 활용하기 좋습니다.

시크릿 참조

1Password CLI의 가장 강력한 기능 중 하나가 바로 시크릿 참조(secret reference)입니다. 시크릿 참조는 op://볼트/항목/필드 형식의 URI로, 1Password에 저장된 값을 가리키는 포인터 역할을 합니다.

op://Development/GitHub Token/password
op://Development/AWS Access Key/access key id
op://Development/Database Password/password

이 참조를 op read 명령어와 함께 쓰면 해당 값을 안전하게 읽어올 수 있어요.

op read "op://Development/GitHub Token/password"

결과

ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

시크릿 참조가 좋은 점은 실제 비밀 값이 코드나 설정 파일에 노출되지 않는다는 것입니다. op://Development/GitHub Token/password라는 문자열 자체는 아무 의미가 없으니까요. .env 파일이 실수로 Git에 커밋되더라도 실제 시크릿이 유출되지 않습니다.

환경 변수 주입

개발하면서 환경 변수로 시크릿을 넘기는 경우가 많죠. op run 명령어를 사용하면 1Password의 시크릿을 환경 변수로 주입하면서 프로세스를 실행할 수 있습니다.

먼저 .env 파일에 시크릿 참조를 넣어둡니다.

.env

DATABASE_URL=op://Development/Database Password/url
API_KEY=op://Development/API Key/credential
GITHUB_TOKEN=op://Development/GitHub Token/password

그런 다음 op run으로 앱을 실행하면 1Password가 시크릿 참조를 실제 값으로 바꿔서 환경 변수로 넘겨줍니다.

op run --env-file=.env -- node server.js

이렇게 하면 server.js가 실행되는 동안 process.env.DATABASE_URL에는 1Password에서 가져온 실제 데이터베이스 URL이 들어가 있게 됩니다. 프로세스가 종료되면 시크릿도 메모리에서 사라지니까 .env 파일에 실제 비밀번호를 적어놓는 것보다 훨씬 안전합니다.

--env-file 없이 인라인으로도 쓸 수 있어요.

DATABASE_URL="op://Development/Database Password/url" op run -- psql

시크릿 주입 (op inject)

환경 변수가 아니라 설정 파일 자체에 시크릿을 주입해야 하는 경우도 있겠죠. op inject 명령어는 템플릿 파일에 있는 시크릿 참조를 실제 값으로 치환해서 출력해줍니다.

예를 들어 이런 템플릿 파일이 있다고 해봅시다.

config.tpl

[database]
host = db.example.com
password = op://Development/Database Password/password

[api]
key = op://Development/API Key/credential

op inject를 실행하면 시크릿 참조가 실제 값으로 바뀐 결과가 출력됩니다.

op inject -i config.tpl -o config.ini

생성된 config.ini 파일에는 1Password에서 가져온 실제 값이 들어가 있어요. 이 파일을 .gitignore에 추가해두면 실수로 커밋될 걱정도 없습니다.

항목 생성과 수정

CLI에서 새 항목을 만들 수도 있습니다. 스크립트에서 자동으로 시크릿을 생성하고 1Password에 저장하는 용도로 유용합니다.

op item create \
  --category login \
  --title "Staging DB" \
  --vault Development \
  --url "https://staging.example.com" \
  --generate-password='letters,digits,symbols,32'

--generate-password 옵션을 쓰면 1Password가 지정한 조건에 맞는 비밀번호를 자동으로 생성해줍니다. 위 예시에서는 영문, 숫자, 특수문자를 포함한 32자리 비밀번호가 만들어집니다.

기존 항목을 수정하려면 op item edit을 사용합니다.

op item edit "Staging DB" --url "https://new-staging.example.com"

항목을 삭제하려면 op item delete를 쓰면 됩니다.

op item delete "Staging DB"

삭제된 항목은 1Password의 휴지통으로 이동하므로 실수로 삭제하더라도 복구할 수 있어요.

SSH 키 관리

1Password CLI는 SSH 키 관리도 지원합니다. SSH 키를 1Password에 저장해두면 여러 기기에서 동일한 키를 안전하게 사용할 수 있고, 에이전트 기능을 통해 ssh 명령어와 자연스럽게 연동됩니다.

1Password 데스크톱 앱에서 설정 > 개발자 > SSH 에이전트 기능을 활성화한 후 SSH 설정 파일에 1Password 에이전트를 연결해줍니다.

~/.ssh/config

Host *
  IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"

이제 ssh 명령어를 사용할 때 1Password에 저장된 SSH 키를 자동으로 사용하게 됩니다. GitHub에 코드를 Push하거나 서버에 SSH로 접속할 때 1Password 앱에서 생체 인증으로 승인하면 되니까 SSH 키 파일을 디스크에 따로 보관할 필요가 없어요.

CI/CD에서 활용

1Password CLI는 CI/CD 파이프라인에서도 활용할 수 있습니다. 1Password에서 제공하는 서비스 계정(Service Account)을 사용하면 사람의 개입 없이 시크릿에 접근할 수 있거든요.

먼저 1Password 웹사이트에서 서비스 계정을 만들고 토큰을 발급받습니다. 그런 다음 CI 환경에서 OP_SERVICE_ACCOUNT_TOKEN 환경 변수로 설정하면 됩니다.

GitHub Actions를 예로 들어보겠습니다.

.github/workflows/deploy.yml

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install 1Password CLI
        uses: 1password/install-cli-action@v1

      - name: Load secrets
        uses: 1password/load-secrets-action@v2
        with:
          export-env: true
        env:
          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
          DATABASE_URL: op://Production/Database/url
          API_KEY: op://Production/API Key/credential

이 방식을 사용하면 GitHub Secrets에는 1Password 서비스 계정 토큰 하나만 저장해두면 됩니다. 나머지 시크릿은 전부 1Password에서 중앙 관리할 수 있어서 시크릿이 여러 곳에 분산되는 문제를 해결할 수 있어요.

시크릿을 교체할 때도 1Password에서 한 번만 바꾸면 모든 CI/CD 파이프라인에 자동으로 반영되니까 관리가 훨씬 수월합니다.

유용한 옵션들

op 명령어에서 자주 쓰이는 옵션 몇 가지를 알아두면 편리합니다.

출력 형식을 지정하는 --format 옵션은 스크립트에서 특히 유용한데요. JSON 형식으로 출력하면 jq 같은 도구와 조합해서 원하는 값을 정확하게 추출할 수 있습니다.

op item list --format json | jq '.[].title'

결과

"AWS Access Key"
"Database Password"
"GitHub Token"

--account 옵션은 여러 1Password 계정을 사용할 때 어떤 계정의 데이터에 접근할지 지정합니다.

op item list --account my-company.1password.com

--vault 옵션으로 특정 볼트를 지정하면 검색 범위를 좁힐 수 있어요.

op item get "API Key" --vault Production

마치며

1Password CLI를 사용하면 시크릿 관리의 많은 고민이 해결됩니다. .env 파일에 평문으로 비밀번호를 적어놓는 대신 시크릿 참조를 사용하고, op run으로 환경 변수를 주입하고, CI/CD에서는 서비스 계정으로 안전하게 시크릿에 접근할 수 있죠.

특히 팀으로 일할 때 1Password의 공유 볼트와 CLI를 함께 쓰면 시크릿을 슬랙이나 이메일로 주고받는 위험한 습관에서 벗어날 수 있습니다. 시크릿 교체도 1Password에서 한 번만 하면 되니까 관리 부담도 크게 줄어들고요.

터미널에서 비밀번호 관리 도구를 사용하는 게 처음에는 좀 낯설 수 있지만, 한번 익숙해지면 브라우저에서 비밀번호를 복사해 붙여넣기 하던 시절로 돌아가기 힘들어질 거예요.

더 자세한 내용은 1Password CLI 공식 문서를 참고하시면 좋겠습니다.

This work is licensed under CC BY 4.0

1Password CLI란?

설치

로그인

볼트와 항목 조회

시크릿 참조

환경 변수 주입

시크릿 주입 (op inject)

항목 생성과 수정

SSH 키 관리

CI/CD에서 활용

유용한 옵션들

마치며

개발자를 위한 뉴스레터

관련 포스트

Homebrew 완벽 가이드: macOS 패키지 관리의 필수 도구

macOS security 명령어로 키체인 다루기

gh skill로 에이전트 스킬 관리하기

GitHub Secret Scanning으로 유출된 비밀 정보 잡아내기