CLI
スクリプト
JSON 出力、ストリーム、終了コード、環境変数、無人実行と CI での実行。
JSON 出力
--json を付けると、stdout にはスペース 2 つでインデントした JSON だけが出力され、メモや進捗は stderr に残り、何も尋ねません。リストは { items, hasMore, nextCursor } を出力し、API のオブジェクトは API が返したとおりに、手書きのコマンドはヘルプに記載のオブジェクトを出力します。
openemail whoami --json | jq -r .workspaceIdopenemail emails list --status failed --json | jq -r ".items[].id"エラーは stderr に 1 行の 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 | 何が問題だったかを 1 文で |
| hint, next | 試すべきことと次に実行するコマンド、または null |
| status, requestId, param, docUrl | エラーが API から来た場合はその値、それ以外は null |
| exitCode | プロセスが終了するときの終了コード |
ストリーム
一部の出力は 1 行に 1 つの JSON オブジェクトが並ぶストリームなので、パイプラインは各項目を届いたそばから処理できます：
- stdout がターミナルでないときの
--all付きのリソース一覧、または--ndjson。--max <n>はその件数で停止します。 openemail temp watch --json。新しいメッセージごとに 1 行。openemail mcp serve。双方向とも 1 行に 1 つの 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、ドキュメントのリンクに使う Web アプリのオリジン |
| 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 など送信が必要になった理由から導いた値にしてください。ステップを再実行すると、二重に送る代わりに最初の送信が返されます。
