1Password Shell Plugins로 CLI 인증 관리하기

CLI 도구를 쓰다 보면 인증 토큰을 어디에 둘지가 늘 고민입니다. GitHub CLI는 GH_TOKEN, Cloudflare Wrangler는 CLOUDFLARE_API_TOKEN 같은 환경 변수를 지원하는데요. 편하다고 셸 설정 파일이나 .env 파일에 토큰을 넣어두면 어느 순간 평문 시크릿이 로컬 디스크 여기저기에 흩어집니다.

1Password에는 이런 문제를 줄여주는 Shell Plugins 기능이 있습니다. CLI가 인증 정보를 필요로 할 때 1Password가 토큰을 꺼내 환경 변수로 주입하고, 사용자는 지문이나 Apple Watch, 시스템 인증으로 승인하는 방식이에요. 토큰을 직접 복사해서 붙여넣거나 셸 프로필에 저장하지 않아도 됩니다.

이번 글에서는 1Password Shell Plugins가 무엇인지 살펴보고, 특히 GitHub CLI(gh)와 Cloudflare Workers CLI(wrangler)에서 어떻게 사용할 수 있는지 알아보겠습니다. 1Password CLI 사용법을 이미 알고 있다면, Shell Plugins는 op를 한 단계 더 편하게 쓰는 기능이라고 보면 됩니다.

Shell Plugins란?

1Password Shell Plugins는 서드파티 CLI의 인증 정보를 1Password에 저장하고, CLI 실행 시점에 필요한 환경 변수로 주입해주는 기능입니다. 예를 들어 GitHub CLI 플러그인은 1Password에 저장된 토큰을 GH_TOKEN으로 주입하고, Cloudflare Workers 플러그인은 CLOUDFLARE_API_TOKEN으로 주입합니다.

겉으로는 평소처럼 gh repo list나 wrangler deploy를 실행합니다. 다만 명령어가 인증 정보를 필요로 하는 순간 1Password가 승인 창을 띄우고, 사용자가 생체 인증이나 시스템 인증으로 승인하면 해당 터미널 세션에서 명령이 이어서 실행됩니다.

지원되는 셸은 Bash, Zsh, fish입니다. 지원되는 CLI도 꽤 많은데요. 내 1Password CLI에서 어떤 플러그인을 지원하는지는 op plugin list로 확인할 수 있습니다.

op plugin list

출력에는 실행 파일 이름, 서비스 이름, 필요한 필드가 함께 나옵니다. 실제로 실행하면 대략 이런 형태입니다.

EXECUTABLE         NAME                  REQUIRED FIELDS
aws                AWS                   Access Key ID, Secret Access Key
codex              OpenAI                API Key
gh                 GitHub                Token
openai             OpenAI                API Key
psql               PostgreSQL            Host, User, Password
stripe             Stripe                Key
vercel             Vercel                Token
wrangler           Cloudflare Workers    Token

예를 들어 gh는 GitHub 토큰을, wrangler는 Cloudflare Workers 토큰을, codex와 openai는 OpenAI API 키를 요구합니다. 그 밖에도 AWS, GitLab, CircleCI, DigitalOcean, Heroku, MongoDB Atlas, MySQL, PostgreSQL, Stripe, Vercel, Sentry, Snowflake, Twilio 같은 서비스가 목록에 보입니다. 평소에 자주 쓰는 CLI가 목록에 있다면 토큰 관리 방식을 정리해볼 만합니다.

동작 방식

Shell Plugins를 설정하면 op plugin init 명령이 특정 CLI의 인증 정보를 1Password 항목과 연결합니다. 이때 새 토큰을 1Password로 가져올 수도 있고, 이미 저장해둔 항목을 검색해서 선택할 수도 있습니다.

그다음 플러그인이 생성한 plugins.sh 파일을 현재 셸에서 source합니다. 이 파일은 gh나 wrangler 같은 명령어를 1Password 플러그인 경유로 실행하도록 셸 alias를 설정합니다. 그래서 사용자는 기존 명령어를 그대로 입력하지만, 인증 정보는 1Password에서 주입되는 구조가 됩니다.

gh repo list
  ↓
1Password Shell Plugin
  ↓
1Password에 저장된 GitHub 토큰을 GH_TOKEN으로 주입
  ↓
GitHub CLI 실행

중요한 점은 토큰이 계속 셸 환경에 남아 있는 방식이 아니라는 것입니다. 1Password가 필요한 순간에 값을 주입하고, 승인된 터미널 세션 안에서만 사용할 수 있게 도와줍니다. 물론 승인된 세션에서는 1Password CLI 명령도 계속 사용할 수 있으므로, 어떤 스크립트와 플러그인을 실행하는지는 신중하게 봐야 합니다.

준비 사항

먼저 1Password 데스크톱 앱과 1Password CLI가 필요합니다. Shell Plugins는 1Password 앱 연동을 전제로 하므로, 앱에서 설정 > 개발자 > CLI 통합 활성화를 켜두어야 합니다.

설치된 op 버전도 확인해봅시다.

op --version

GitHub 플러그인은 1Password CLI 2.9.0 이상, Cloudflare Workers 플러그인은 2.12.0 이상이 필요합니다. 요즘 설치한 1Password CLI라면 대부분 문제없겠지만, 오래전에 설치했다면 업데이트하는 편이 좋습니다.

그리고 사용할 CLI도 설치되어 있어야 합니다. GitHub CLI는 GitHub CLI 사용법에서, Wrangler는 Wrangler CLI 사용법에서 자세히 다루고 있습니다.

GitHub CLI 인증하기

GitHub CLI는 보통 gh auth login으로 브라우저 인증을 진행합니다. Shell Plugin을 사용하면 GitHub Personal Access Token을 1Password에 저장해두고, gh 실행 시 GH_TOKEN으로 주입할 수 있습니다.

먼저 GitHub에서 Personal Access Token을 만듭니다. 이미 1Password에 저장해둔 토큰이 있다면 그대로 사용하면 되고, 없다면 토큰 생성 후 1Password 브라우저 확장으로 저장해두면 편합니다.

그다음 1Password에 로그인합니다.

op signin

GitHub 플러그인을 초기화합니다.

op plugin init gh

실행하면 1Password에 새 항목을 가져올지, 기존 항목을 검색해서 선택할지 묻습니다. 이미 GitHub 토큰을 1Password에 저장했다면 기존 항목을 선택하면 되고, 아직 없다면 가져오기 흐름에서 토큰을 입력해 새 항목으로 저장할 수 있습니다.

마지막으로 이 토큰을 언제 사용할지 정합니다. 개인 GitHub 계정 하나만 사용한다면 전역 기본값으로 설정해도 됩니다. 반대로 회사 계정과 개인 계정을 나눠 쓴다면 특정 디렉터리와 그 하위 디렉터리에서만 사용하도록 설정하는 편이 안전합니다. 예를 들어 회사 저장소가 ~/work/company 아래에 모여 있다면 그 디렉터리에서 op plugin init gh를 실행하고 디렉터리 범위를 선택하는 식입니다.

플러그인 설정이 끝나면 plugins.sh를 source하라는 안내가 나옵니다. 경로는 1Password 설정 디렉터리에 따라 달라질 수 있지만, 일반적으로는 다음과 비슷합니다.

source ~/.config/op/plugins.sh

계속 사용하려면 이 줄을 ~/.zshrc나 ~/.bashrc에 추가합니다. 처음에는 현재 터미널에서만 source해서 테스트해보고, 괜찮으면 셸 설정 파일에 넣는 흐름을 추천합니다.

이제 gh 명령어를 실행해봅니다.

gh repo list

인증이 필요한 명령이면 1Password 승인 창이 뜨고, 승인 후 GitHub CLI가 실행됩니다. 토큰을 셸 프로필에 직접 넣지 않고도 gh를 사용할 수 있는 셈이죠.

Cloudflare Wrangler 인증하기

Cloudflare Workers를 개발하다 보면 wrangler login으로 브라우저 인증을 하거나, CLOUDFLARE_API_TOKEN 환경 변수를 사용하게 됩니다. Shell Plugin을 쓰면 Cloudflare API 토큰을 1Password에 저장해두고 Wrangler 실행 시 자동으로 주입할 수 있습니다.

Wrangler 플러그인도 흐름은 거의 같습니다. 먼저 1Password에 로그인합니다.

op signin

그다음 Cloudflare Workers 플러그인을 초기화합니다.

op plugin init wrangler

이 과정에서 Cloudflare 토큰을 새 1Password 항목으로 가져오거나, 이미 저장된 항목을 선택할 수 있습니다. Cloudflare Workers 플러그인이 기대하는 필드는 Token이고, 이 값은 CLOUDFLARE_API_TOKEN 환경 변수로 주입됩니다. 계정 ID가 필요한 경우 Account ID 필드를 추가할 수 있고, 이 값은 CLOUDFLARE_ACCOUNT_ID로 주입됩니다.

설정 범위도 GitHub와 마찬가지로 고를 수 있습니다. Worker 프로젝트별로 Cloudflare 계정이 다르다면 프로젝트 디렉터리 범위를 선택하는 편이 좋습니다. 개인 계정 하나로만 배포한다면 전역 기본값도 괜찮습니다.

plugins.sh를 source한 뒤 평소처럼 Wrangler를 실행합니다.

wrangler whoami
wrangler deploy

인증이 필요한 순간 1Password가 승인 창을 띄우고, 승인하면 Wrangler가 필요한 환경 변수를 받아 실행됩니다. 기존에 로컬 디스크에 저장해둔 Cloudflare 토큰이 있다면, 1Password에 저장한 뒤에는 평문 파일이나 셸 설정에서 제거하는 것이 좋습니다.

설정 확인과 초기화

어떤 인증 정보가 어떤 범위로 설정되어 있는지 확인하려면 op plugin inspect를 사용합니다.

op plugin inspect gh
op plugin inspect wrangler

설정을 지우고 싶다면 op plugin clear를 사용합니다.

op plugin clear gh
op plugin clear wrangler

Shell Plugins의 기본값에는 우선순위가 있습니다. 터미널 세션 기본값이 가장 먼저 적용되고, 그다음 현재 디렉터리부터 홈 디렉터리까지의 디렉터리별 기본값, 마지막으로 전역 기본값이 적용됩니다. 그래서 같은 도구에 여러 범위의 기본값이 잡혀 있다면 clear를 여러 번 실행해야 할 수도 있습니다.

모든 범위를 한 번에 지우고 싶다면 --all 옵션을 붙입니다.

op plugin clear gh --all
op plugin clear wrangler --all

여러 계정이나 여러 환경을 쓰는 경우에는 이 우선순위를 이해해두는 게 중요합니다. 예상과 다른 계정으로 gh나 wrangler가 실행된다면, 먼저 op plugin inspect로 현재 적용 중인 기본값을 확인하세요.

보안상 알아둘 점

Shell Plugins는 토큰을 평문 파일에 저장하지 않도록 도와주지만, 모든 위험을 없애주는 마법은 아닙니다. 1Password 승인 후에는 해당 터미널 창이나 탭에 세션이 생기고, 그 세션에서는 같은 플러그인뿐 아니라 다른 1Password CLI 명령도 추가 승인 없이 실행될 수 있습니다.

공식 문서에 따르면 세션은 1Password가 잠기거나, 10분 동안 사용하지 않거나, 12시간이 지나거나, op signout을 실행하면 종료됩니다. 즉, 한 번 승인한 터미널에서는 신뢰하지 않는 스크립트를 실행하지 않는 습관이 여전히 중요합니다.

또한 1Password는 공식 CLI에 포함된 플러그인만 검토했다고 안내합니다. 직접 작성한 플러그인을 테스트하는 경우가 아니라면, 임의의 바이너리를 ~/.op/plugins/local 같은 위치에 내려받아 실행하는 방식은 피하는 편이 좋습니다.

언제 쓰면 좋을까?

Shell Plugins는 로컬 개발 환경에서 특히 유용합니다. 예를 들어 개인 GitHub 계정과 회사 GitHub 계정을 디렉터리별로 나눠 쓰거나, 여러 Cloudflare 계정을 프로젝트별로 오갈 때 편합니다. 토큰을 셸 프로필에 넣지 않아도 되고, 어떤 디렉터리에서 어떤 자격 증명을 쓸지 1Password가 관리해주기 때문입니다.

반대로 CI/CD에서는 보통 Shell Plugins보다 서비스 계정이나 전용 액션을 쓰는 편이 맞습니다. GitHub Actions에서 1Password 시크릿을 읽는 방법은 GitHub Actions에서 1Password 시크릿 사용하기에서 따로 다뤘습니다. Shell Plugins는 사람이 터미널에서 직접 명령을 실행하는 환경에 더 잘 맞습니다.

마치며

1Password Shell Plugins를 사용하면 GH_TOKEN이나 CLOUDFLARE_API_TOKEN 같은 값을 셸 프로필에 평문으로 남기지 않아도 됩니다. 평소처럼 gh와 wrangler를 실행하면서, 실제 토큰은 1Password에 저장하고 필요할 때만 생체 인증으로 꺼내 쓰는 흐름을 만들 수 있죠.

처음에는 op plugin init, plugins.sh, 기본값 범위 같은 개념이 조금 낯설 수 있습니다. 하지만 한 번 설정해두면 GitHub와 Cloudflare처럼 자주 쓰는 CLI 인증이 훨씬 깔끔해집니다. 특히 여러 계정과 여러 프로젝트를 오가는 개발자라면 디렉터리별 기본값만으로도 체감이 꽤 클 거예요.

더 자세한 내용은 1Password의 Shell Plugins 공식 문서와 GitHub 플러그인 문서, Cloudflare Workers 플러그인 문서를 참고하세요.