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

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

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

```sh
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`은 갱신 토큰을 서버에서 폐기한 뒤 저장된 항목을 삭제합니다. 폐기가 실패하면 로그아웃을 다시 실행하세요.

## 값과 덮어쓰기 선택하기

```sh
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`로 저장한 뒤 실행합니다.

```sh
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` 결과를 단계 출력에 넣거나 시크릿 파일을 작업 로그에 출력하지 마세요.

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

```sh
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` 같은 셸 리디렉션은 셸이 처리하므로 이 파일 보호를 적용받지 않습니다.