CLI
스크립트
JSON 출력, 스트림, 종료 코드, 환경 변수, 무인 실행과 CI 실행.
JSON 출력
--json을 주면 stdout에는 공백 두 칸으로 들여 쓴 JSON만 나오고, 메모와 진행 상황은 stderr에 남으며, 아무것도 묻지 않습니다. 목록은 { items, hasMore, nextCursor }를, API 객체는 API가 반환한 그대로를, 직접 작성한 명령은 도움말에 설명된 객체를 출력합니다.
openemail whoami --json | jq -r .workspaceIdopenemail emails list --status failed --json | jq -r ".items[].id"오류는 stderr에 JSON 한 줄로 나가며, 종료 코드는 사람이 받았을 것과 같습니다:
{"error":{"type":"permission_error","code":"insufficient_scope","message":"This API key does not have the domains:write scope.","hint":"The credential is missing a scope this call needs. Use a key that has it, or sign in again with openemail login.","next":null,"status":403,"requestId":"req_7Hc2kQ","param":null,"docUrl":"https://openemail.uk/docs/api/errors#insufficient_scope","exitCode":4}}| 필드 | 담긴 내용 |
|---|---|
| type | API 오류 타입, 또는 CLI 내부 실패일 때 cli_error, network_error, internal_error |
| code | insufficient_scope, not_signed_in, unknown_flag 같은 안정된 코드 |
| message | 무엇이 잘못됐는지 한 문장으로 |
| hint, next | 시도할 것과 다음에 실행할 명령, 또는 null |
| status, requestId, param, docUrl | 오류가 API에서 왔으면 API의 값, 아니면 null |
| exitCode | 프로세스가 끝날 때의 종료 코드 |
스트림
일부 출력은 한 줄에 하나씩 JSON 객체가 이어지는 스트림이므로, 파이프라인이 각 항목을 도착하는 즉시 처리할 수 있습니다:
- stdout이 터미널이 아닐 때
--all을 쓴 리소스 목록, 또는--ndjson.--max <n>은 그 개수에서 멈춥니다. openemail temp watch --json, 새 메시지마다 한 줄.openemail mcp serve, 양방향 모두 한 줄에 JSON-RPC 메시지 하나.
openemail contacts list --all > contacts.ndjsonopenemail emails list --status failed --all --max 500 | jq -r .id종료 코드
| 코드 | 의미 |
|---|---|
| 0 | 완료 |
| 1 | 예상치 못한 실패, 서버 오류, 또는 실패한 보내기 |
| 2 | 사용 오류: 잘못된 인수, 알 수 없는 명령이나 플래그, 물을 수 없었던 값이나 확인, 또는 CLI가 자격 증명을 보내지 않을 오리진이나 경로 |
| 3 | 로그인하지 않았거나, 로그인이 거부되었거나 만료되었거나 명령 실행 중에 로그아웃됨 |
| 4 | 허용되지 않음: 범위나 권한 부족, 물을 수 없었거나 일시 중지된 인증 코드, 또는 브라우저 로그인이 필요한 곳의 API 키 |
| 5 | 찾을 수 없음 |
| 6 | 현재 상태와 충돌 |
| 7 | 입력이 잘못됨 |
| 8 | 요청 한도 초과, 또는 AI 할당량 소진 |
| 9 | 네트워크 실패 또는 시간 초과 |
| 10 | 취소됨: 확인이나 프롬프트를 거절함 |
| 130, 143 | Ctrl+C나 SIGTERM으로 중지됨 |
환경 변수
| 변수 | 하는 일 |
|---|---|
| OPENEMAIL_API_KEY | 저장된 어떤 프로필 대신 쓸 API 키 |
| OPENEMAIL_PROFILE | 사용할 저장된 프로필 |
| OPENEMAIL_BASE_URL | OPENEMAIL_API_KEY, --api-key, 그리고 자격 증명을 보내지 않는 명령이 쓰는 API 오리진. 저장된 로그인은 로그인한 API로만 갑니다 |
| OPENEMAIL_APP_URL | 로그인, open, 문서 링크에 쓰는 웹 앱 오리진 |
| OPENEMAIL_CONFIG_DIR | 프로필과 받은편지함 토큰을 보관하는 곳. 설정하지 않으면 ~/.openemail |
| OPENEMAIL_NO_UPDATE_CHECK | npm에서 새 릴리스를 절대 확인하지 않음. OPENEMAIL_DISABLE_UPDATE_NOTICE도 같음 |
| NO_COLOR, FORCE_COLOR=0 | 색 없음 |
| CI | 절대 묻지 않고, 브라우저를 열지 않고, 업데이트를 확인하지 않음. 대부분의 CI 서비스는 이 변수가 없어도 인식됩니다 |
| VISUAL, EDITOR | send와 reply가 본문 작성에 여는 편집기 |
무인 실행
CLI는 stdin과 stdout이 모두 터미널이고 --json, --no-input, CI 중 어느 것에도 해당하지 않을 때만 묻습니다. 그렇지 않으면:
- 필수 값이 빠지면 종료 코드
2로 멈추고 넘겨야 할 플래그를 알려 줍니다. - 파괴적인 명령은
--yes를 주지 않는 한Refusing to run unattended. Pass --yes to confirm.과 종료 코드2로 멈춥니다. - 인증 코드가 필요한 변경은 입력할 사람이 없으므로 종료 코드
4로 멈춥니다. API 키를 쓰거나 먼저openemail verify를 실행하세요.
CI에서
작업에는 필요한 범위만 가진 API 키를 주고, 시크릿에 보관해 OPENEMAIL_API_KEY로 넘기세요. 아무것도 저장되지 않고, 아무것도 묻지 않으며, 업데이트 확인도 실행되지 않습니다.
- name: Tell the team env: OPENEMAIL_API_KEY: ${{ secrets.OPENEMAIL_API_KEY }} run: | npx -y @openemail/[email protected] send \ --from [email protected] \ --to [email protected] \ --subject "Deployed ${{ github.sha }}" \ --text "Build ${{ github.run_number }} is live." \ --idempotency-key "deploy-${{ github.run_id }}"ADDRESS=$(npx -y @openemail/[email protected] temp new --ttl 15)./signup-test.sh "$ADDRESS"npx -y @openemail/[email protected] temp watch --first --json | jq -r .snippetnpx -y @openemail/[email protected] temp delete --yesfailed=$(openemail emails list --status failed --json | jq ".items | length")test "$failed" -eq 0파이프라인이 재시도할 수 있는 보내기에는 --idempotency-key를 주고, 실행 ID처럼 보내기가 필요해진 이유에서 값을 만드세요. 그러면 단계를 다시 실행해도 두 번 보내는 대신 첫 보내기를 돌려받습니다.
