터미널에서 시크릿 사용하기

npm install -g @mocco/cli로 CLI를 설치합니다. mocco secrets run은 평문 파일을 만들지 않고 읽기 권한이 있는 값을 한 명령에 전달합니다.

로그인하고 프로젝트 연결하기

mocco login
mocco link --workspace <workspace-uuid> --project <project-uuid> --env development --path /
mocco secrets run -- yarn dev

로그인하면 같은 컴퓨터의 브라우저가 열립니다. mocco login --no-browser는 대신 인증 URL을 출력합니다. 콜백은 127.0.0.1에서만 수신하며 로그인 대기 시간은 5분입니다. 브라우저가 없는 환경에서는 API 키를 사용합니다.

mocco link는 터미널에서 누락된 값을 묻습니다. 스크립트에서는 네 플래그를 모두 지정하세요. 워크스페이스와 프로젝트 UUID는 콘솔 URL에서 복사합니다. 생성되는 .mocco.json에는 ID와 기본값만 있어 커밋할 수 있습니다. CLI는 현재 디렉터리에서 상위로 검색하고 Git 저장소 루트에서 멈춥니다.

계정의 권한은 콘솔과 같습니다. 프로덕션 시크릿의 설명만 볼 수 있고 값을 공개할 수 없는 멤버는 CLI에서도 값을 읽을 수 없습니다. mocco whoami는 검증된 계정 ID를 출력합니다. 토큰 서명·발급자·시크릿 대상·범위·만료를 로컬에서 검사하며, 이미 발급된 액세스 토큰의 즉시 폐기를 보장하지는 않습니다.

인증 정보는 API URL별로 $XDG_CONFIG_HOME/mocco/credentials.json에 저장하며, XDG 설정이 없으면 ~/.config/mocco/credentials.json을 사용합니다. Windows는 %APPDATA%\mocco\credentials.json을 사용합니다. 현재 사용자만 파일에 접근할 수 있으며 만료된 액세스 토큰은 자동 갱신됩니다. mocco logout은 갱신 토큰을 서버에서 폐기한 뒤 저장된 항목을 삭제합니다. 폐기가 실패하면 로그아웃을 다시 실행하세요.

값과 덮어쓰기 선택하기

mocco secrets run --env staging --path /api -- node server.js
mocco secrets run --keep-env -- yarn dev
mocco secrets run --strict -- yarn test

기본적으로 시크릿이 상속된 환경 변수를 덮어씁니다. --keep-env는 상속된 값을 우선합니다. 해결되지 않은 참조는 키 이름과 이유만 경고하며, --strict는 명령 실행이나 출력 전에 중단합니다. macOS와 Linux에서는 인자를 해석 없이 그대로 전달하며 표준 입력을 파이프로 전달하거나 리다이렉트해도 사용 가능한 제어 터미널을 유지합니다. 키보드 Ctrl+C는 명령에 한 번 전달됩니다. Windows에서는 PATH와 PATHEXT로 실행 파일과 .cmd 도구를 찾고 shim 인자를 이스케이프합니다. macOS와 Linux에서는 종료 신호를 자식 프로세스 그룹에 전달하고 종료 코드와 신호를 보존하며, Windows에서는 필요할 때 프로세스 트리를 종료합니다.

개인 계정에서는 --workspace와 --project가 연결된 ID보다 우선합니다. 환경은 --env, MOCCO_ENV, 연결된 환경 순서이며 폴더는 --path, 연결된 폴더 순서입니다. API URL은 --api-url, MOCCO_API_URL, 기본값 https://www.mocco.club/api/ext/v1 순서입니다. HTTPS와 로컬 루프백 HTTP URL만 허용합니다.

CI에서 API 키 사용하기

필요한 시크릿 환경과 폴더 glob에 바인딩된 secrets:read 시크릿 API 키를 만듭니다. CI 제공자의 시크릿 저장소에 MOCCO_API_KEY로 저장한 뒤 실행합니다.

mocco whoami
mocco secrets run --strict -- yarn build

MOCCO_API_KEY가 설정되어 있으면 저장된 개인 로그인보다 항상 우선합니다. 키가 잘못되었거나 비어 있으면 개인 계정으로 재시도하지 않습니다. 프로젝트는 키가 결정합니다. 환경과 폴더는 플래그, MOCCO_ENV(환경만), .mocco.json 순서로 선택하며 모든 요청은 키의 환경과 폴더 권한 안에 있어야 합니다. whoami는 프로젝트·범위·시크릿 환경 ID·폴더 glob을 보여줍니다.

GitHub Actions에서는 마스크와 자식 프로세스의 표준 출력·표준 오류를 하나의 순서가 보장된 표준 출력 로그 채널로 보냅니다. 모든 마스크를 먼저 쓰고 자식의 두 출력 스트림을 그 채널에 연결하므로, 별도 표준 오류 파이프에서 마스크 등록보다 값이 먼저 노출되는 경합을 막습니다. 자식의 표준 입력은 그대로 상속하며 종료 코드와 신호도 보존합니다. GitHub Actions 밖에서는 표준 출력과 표준 오류가 기존처럼 동작합니다.

CI에서는 run을 권장합니다. CI의 표준 출력은 작업 로그이므로, 구조화된 데이터를 저장하려면 표준 출력 파이프라인 대신 자식 도구의 파일 출력 옵션(예: --output result.json)을 사용하세요. GitHub Actions의 pull은 --output 파일을 반드시 지정해야 하며, 파일이 없으면 시크릿을 요청하기 전에 중단합니다. JSON 파일은 유효한 JSON으로 유지하고 마스크 명령은 순서가 보장된 작업 로그에 씁니다. pull 결과를 단계 출력에 넣거나 시크릿 파일을 작업 로그에 출력하지 마세요.

파일로 명시적으로 내보내기

mocco secrets pull --output .env.local
mocco secrets pull --format json --output secrets.local.json
mocco secrets pull --env development

--output이 없으면 pull은 dotenv를 표준 출력에 씁니다. 다만 GitHub Actions에서는 앞서 설명한 대로 --output이 필수입니다. JSON 출력은 문자열 값으로 이루어진 객체입니다. 파일은 UTF-8·LF, 제한된 권한, 원자적 교체로 저장합니다. Dotenv 파일에는 출처 주석을 넣고 JSON은 유효한 JSON으로 유지합니다. 콘솔과 CLI는 여러 줄 값을 포함한 dotenv 인용 규칙을 공유합니다.

Git 저장소에서는 먼저 대상 경로를 .gitignore에 추가하세요. CLI는 무시되지 않는 경로와 이미 Git에서 추적하는 파일 모두 거부합니다. --force는 Git 보호를 건너뛰지만 심볼릭 링크는 계속 거부합니다. > .env 같은 셸 리디렉션은 셸이 처리하므로 이 파일 보호를 적용받지 않습니다.