empa — EMPA コマンドライン CLI
empa は EMPA 各サービス (Account / Receiver / CMS / Sites) を
コマンドラインから操作するための CLI です。gh や aws
と同じ感覚で、アカウントを切り替えながら複数テナント・複数環境
(dev / stg / prd) を扱えます。
概要
認証は EMPA Account の OAuth 2.0 プロバイダに対して Authorization Code + PKCE で行い、取得したトークンを OS の secret store (Linux は Secret Service / macOS は Keychain / Windows は Credential Manager) に保管します。secret store が無いヘッドレス環境では permission 0600 の file fallback に自動退避します。
- 対応 OS: Linux / macOS / Windows (amd64 / arm64)
- 配布: 公開 CloudFront チャンネル
cli.empa.jp(GitHub / Homebrew 不要) - 自己更新:
empa updateが sigstore 署名検証付きでバイナリを差し替え - 自動化:
empa mcpで Model Context Protocol サーバとしても起動可能
インストール
クイックインストール (curl | bash, 推奨)
curl -fsSL https://cli.empa.jp/prd/stable/install.sh | bash
OS / アーキテクチャを自動判定し、公開 CloudFront 配布から最新の
stable 版 empa を取得します。ダウンロード後に
checksums.txt の sha256 を検証してから PATH
上にインストールします。GitHub や Homebrew へのアクセスは不要です。
環境変数で挙動を調整できます:
| 変数 | 既定値 | 意味 |
|---|---|---|
EMPA_VERSION | (最新) | タグを固定。例 v1.2.2 |
EMPA_INSTALL_DIR | 書込可なら /usr/local/bin、無理なら ~/.local/bin | インストール先ディレクトリ |
# 例: ~/bin にインストール
curl -fsSL https://cli.empa.jp/prd/stable/install.sh | EMPA_INSTALL_DIR="$HOME/bin" bashインストール後の更新は empa update で行います (同じ CloudFront チャンネルを追従)。
Homebrew: brew install empa の tap は現時点では未提供です。上記のインストールスクリプトか直接ダウンロードを使ってください。
直接ダウンロード (CloudFront, cli.empa.jp/prd/)
アーカイブ・チェックサム・署名は https://cli.empa.jp/prd/ から匿名で取得できます。
empa update が追従する経路でもあります
(ソースリポジトリが private でも取得可能)。
# os_arch: linux_amd64 | linux_arm64 | darwin_amd64 | darwin_arm64
VERSION=v1.0.0
OS_ARCH=linux_amd64
BASE=https://cli.empa.jp/prd/releases/${VERSION}
curl -fSLO ${BASE}/empa_${VERSION}_${OS_ARCH}.tar.gz
curl -fSLO ${BASE}/checksums.txt
sha256sum -c --ignore-missing checksums.txt
tar xzf empa_${VERSION}_${OS_ARCH}.tar.gz
sudo install -m 0755 empa /usr/local/bin/empa
empa version現行の stable バージョンは manifest で確認できます:
Windows は _windows_amd64.zip を展開し、empa.exe を
%PATH% の通った場所に置いてください。
リリースの検証 (cosign keyless / sigstore)
リリースは cosign keyless
で署名されています (公開鍵ファイルの管理不要)。checksums.txt と並んで
sigstore バンドル checksums.txt.sigstore が公開されます。
cosign verify-blob \
--certificate-identity-regexp 'https://github.com/(respect-pal-jp|tomose-grp)/empa-services/\.github/workflows/cli-release\.yml@.+' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
--bundle checksums.txt.sigstore \
checksums.txt
empa update は同等の検証を埋め込み済みの sigstore-go で
プロセス内実行するため、外部 cosign は不要です。手動検証は初回 install
のときのみで十分です。
アカウントの選択
empa は本番 (PRD) の EMPA に接続します。1 つのインストールで
複数のアカウント (テナント) を切り替えながら操作できます。対象アカウントは
グローバルな --account <アカウント名> フラグ
(または EMPA_ACCOUNT 環境変数) で指定します。
| 項目 | 値 |
|---|---|
| 既定環境 | prd (本番) |
| Account ホスト | https://{account_code}.account.empa.jp |
empa login --account acme # account "acme" にログイン
empa cms content list --account acme
EMPA_ACCOUNT=acme empa whoami
選択の優先順位 (上が強い): --account フラグ →
EMPA_ACCOUNT → --profile (非推奨) →
EMPA_PROFILE (非推奨) → config.toml の
default_profile。認証トークンはアカウント単位で分離されるため、
複数アカウントの認証情報が混ざることはありません。
5 分チュートリアル
-
ログイン — ブラウザが開き、同意するとトークンが保管されます。
ブラウザを開けない環境 (SSH / WSL / Docker) では
--no-browserを付けます。empa login --account acme empa login --account acme --no-browser # 別マシンで authorize URL を開く -
自分のセッションを確認
empa whoami empa account show -
利用可能な app を確認 — 出力の
appCodeを以降の--appで使うか、profile のdefault_appに保存します。empa account apps empa account apps --service receiver empa config set profiles.acme.default_app contact -
最初の API 呼び出し — 出力は TTY なら table、pipe なら JSON が既定。
--format json|yaml|tableで明示できます。empa receiver form list empa receiver form list --format json | jq '.[].slug' -
ヘルスチェック — profile に紐づくサービスの
/upを並列で確認。empa status
グローバルフラグ
すべてのコマンドで共通して使えるフラグです。正確な一覧は empa <command> --help を参照してください。
| フラグ | 環境変数 | 意味 |
|---|---|---|
--account <name> | EMPA_ACCOUNT | 操作対象のアカウントを選択 |
--app <code> | EMPA_APP | 対象 app コード |
--format json|yaml|table | — | 出力形式 (既定: TTY→table / それ以外→json) |
--output <file> | — | stdout の代わりにファイルへ書き出す |
-v, --verbose | — | 詳細出力 |
-q, --quiet | — | 非必須の出力を抑制 |
--no-pager | — | pager を通さない |
--dry-run | — | 副作用を起こさず実行内容のみ表示 |
--no-update-check | EMPA_NO_UPDATE_CHECK | 起動時のバージョン確認を 1 回スキップ |
--profile <name> | EMPA_PROFILE | 非推奨: --account のエイリアス |
認証 / カタログ
| コマンド | 用途 |
|---|---|
empa login | ブラウザを開き PKCE フロー → トークン保管 |
empa logout | refresh token を失効し、ローカルの secret を消去 |
empa whoami | 現在のセッション概要を 1 行で表示 |
empa profile list/show/use/add/remove | profile カタログの管理 |
empa config get/set/list | config.toml をドット区切りキーで編集 |
profile add の最小形は profile 名と Account のベース URL だけを取り、
account_code / environment /
endpoint_account_template をホストから推測します。
empa profile add cms-example https://cms-example.account.empa.jp/
empa login # 直前に追加した profile が default_profile になるaccount / me
| コマンド | 用途 |
|---|---|
empa account show | GET /api/account |
empa account apps [--service receiver|cms] | 契約している app の一覧 |
empa me show | GET /api/me |
empa me update --display-name --email | PATCH /api/me |
empa me password change | TTY 入力でパスワード変更 |
empa me tokens list/revoke | refresh token の管理 |
receiver
| コマンド | 用途 |
|---|---|
empa receiver form list/show/pull/create/update/delete/restore | フォームの CRUD + YAML ラウンドトリップ |
empa receiver form publish/unpublish | (no-op: Receiver に draft/publish は無い) |
empa receiver submission list/show/export | サブミッション閲覧 & CSV/JSON エクスポート |
empa receiver notification list/show/update | FormAction (通知) の管理 |
# フォーム定義を YAML に書き出して編集し、反映する
empa receiver form pull contact > contact.yaml
empa receiver form update contact -f contact.yaml
# サブミッションを CSV でエクスポート
empa receiver submission export contact --format csv --output submissions.csvcms
| コマンド | 用途 |
|---|---|
empa cms content list/show/pull/create/update/publish/withdraw/delete | コンテンツエントリの CRUD + YAML ラウンドトリップ |
empa cms template list/show/pull/create/update/delete | コンテンツスキーマ (テンプレート) の CRUD |
empa cms media list/upload/delete/restore | メディアファイル管理 (UPSERT / ソフトアーカイブ / 7 日以内復元) |
empa cms content file upload | ContentEntry の file 型フィールドへファイルをアップロード |
empa cms delivery preview | 署名付き配信プレビュー URL を発行 |
empa cms delivery sdk download | 動的生成された TypeScript SDK (tar.gz) をダウンロード |
# 公開ワークフロー
empa cms content pull news article-42 > article-42.yaml
empa cms content update news article-42 -f article-42.yaml
empa cms content publish news article-42
# メディアをアップロードして相対パスを得る
empa cms media upload ./hero.png # -> {contentEntryKey}/hero.png を payload に格納sites (EMPA Sites)
empa sites は EMPA Sites のコントロールプレーン (リポジトリ source の
登録 → ビルド → image のデプロイ → 環境変数 / ルーティング / 証明書の設定) を
操作します。接続先ホストは receiver / cms と同じく アクティブな app
(--app または profile の default_app) から解決され、
profile の endpoint_sites で固定することもできます。
コマンドツリーは 3 つのプレーンに分かれます。各リソースは 数値 id
で参照し、親リソースを絞り込む --source / --site /
--environment などのフラグを伴います。create /
update は 渡したフラグだけを適用します。
Build プレーン (source / build / image)
| コマンド | 用途 |
|---|---|
empa sites source list/show/create/update/delete/verify | リポジトリ source の CRUD + 規約チェック (verify で conventionStatus を再判定) |
empa sites build list/show/kick | git ref → ECR image のビルドを発火 (非同期: pending → building → succeeded/failed) し状態を確認 |
empa sites image list/show | デプロイ可能な image 一覧 (--source で絞り込み可) |
Deploy プレーン (site / environment / deployment)
| コマンド | 用途 |
|---|---|
empa sites site list/show/create/update/delete | site の CRUD (--source に紐付け)。slug は全テナントで一意・最大 59 文字。slugConflict: true は slug が他のサイトと重複していて自動割当ホストを配線できない状態で、site update <id> --slug で slug を変えると解消します |
empa sites environment list/show/create/update/delete | environment の CRUD (--tier / --task-memory / --task-cpu / autoscale)。alias env |
empa sites deployment list/show/create/rollback | image を environment にデプロイ / 過去 image へロールバック。alias deploy |
Config プレーン (env-var / secret / routing-rule / certificate)
| コマンド | 用途 |
|---|---|
empa sites env-var list/create/update/delete | 平文の環境変数 (--environment 単位) |
empa sites secret list/create/update/delete | secret 参照。値は write-only — 書き込み時のみ送信され、いかなる読み出しでも返りません (list は key / ARN / lastSetAt のみ)。alias secrets |
empa sites routing-rule list/create/update/delete | ホスト / パスのルーティングルール (--priority は environment 内で一意)。カスタムドメインのホストには、運用者が承認済みのドメインの証明書が要ります (承認待ちの間は 422)。運用者がドメインの利用を取り消した / 別のアプリへ付け替えたルールはサーバが無効化し、list に disabled (ownership_revoked) と出ます。承認を得てから routing-rule update <id> (フラグなしで可) で保存し直すと有効に戻ります。alias routing |
empa sites certificate list/show/create/delete/request-validation | TLS 証明書 (--cert-type acm|imported|csr、csr は --key-algorithm ec_p256|rsa_2048)。list / show に運用者の承認の状態 (domainClaimStatus)・所有確認・残り日数。新しいドメインは EMPA の運用者の承認が要ります (証明書を作ると申請が自動ででき、承認されるまでは issued でもルーティングルールに設定できません。発行の手続きは進められます)。request-validation で ACM DNS 検証を再要求 (acm のみ)。alias cert |
empa sites certificate verify-ownership/upload/csr/regenerate-csr | imported / csr: TXT で所有確認 → upload --certificate-file --chain-file [--private-key-file] で ACM へ import (再実行で更新)。秘密鍵はファイルパスでのみ受け付けます。csr [--output] で CSR を取得、regenerate-csr で鍵を更新。秘密鍵のエクスポートは CLI / MCP 非対応 (画面のみ) |
secret は write-only です。値はサーバ側で secret manager に直接書き込まれ
(CLI / API は ARN 参照だけを保持)、読み出しでは決して返りません。平文をシェル履歴に
残さないため、--value を省略して標準入力 (stdin) から渡せます。
Staff 向けの hosting クラスタ / quota API は内部 (caller=base) であり、
意図的に CLI のスコープ外です。
# 1) リポジトリを source として登録し、規約チェックを走らせる
empa sites source create --name corp-web --repo-url https://github.com/acme/corp-web \
--provider github --framework nextjs
empa sites source verify 12
# 2) git ref からビルドを発火し、完了をポーリング
empa sites build kick --source 12 --ref main
empa sites build show 87 # status: pending → building → succeeded
# 3) site と environment を用意して image をデプロイ
empa sites site create --source 12 --name corp-web --slug corp-web
empa sites environment create --site 5 --tier production --task-memory 1024 --task-cpu 512
empa sites image list --source 12
empa sites deployment create --environment 9 --image 34
# 4) 過去 image へロールバック (再ビルドせず digest を再適用)
empa sites deployment rollback --environment 9 --image 30
# 5) secret は値を stdin で渡してシェル履歴に残さない (--value は省略)
printf '%s' "$DATABASE_URL" | empa sites secret create --environment 9 --key DATABASE_URL横断コマンド (status / update / completion / version)
| コマンド | 用途 |
|---|---|
empa status | account / receiver / cms の /up を並列プローブ |
empa update [--check] | CloudFront manifest + sigstore 検証で自己更新 |
empa completion bash|zsh|fish|powershell | シェル補完スクリプトを生成 |
empa version [--format json] | ビルド情報を表示 |
自動更新 (empa update)
実行中のバイナリをその場で置き換えます。外部 cosign は不要で、
sigstore 検証は埋め込みの sigstore-go と埋め込みの Sigstore public-good
trusted root でプロセス内実行します。
- CloudFront の stable チャンネル manifest (
stable/latest.json) を取得 - manifest のバージョンが
empa versionと一致すればスキップ - OS/arch に対応するアーカイブと
checksums.txt(.sigstore)を解決 - sigstore バンドルを端から端まで検証 (Fulcio 証明書チェーン / Rekor inclusion proof / GitHub Actions リリースワークフロー OIDC identity)
- アーカイブの sha256 を検証し、現在の実行ファイルへアトミックに置換
empa update # 最新 stable に更新
empa update --check # 最新版の表示のみ
config.toml で [update] notify_on_start = true を設定すると、
起動時に新しい stable があれば 1 行のヒントを stderr に出します
(24h キャッシュ・コマンド実行はブロックしない)。
empa config set update.notify_on_start true で切り替えられます。
シェル補完
# bash (Linux)
empa completion bash | sudo tee /etc/bash_completion.d/empa
# zsh
empa completion zsh > "${fpath[1]}/_empa"
# fish
empa completion fish > ~/.config/fish/completions/empa.fish
# PowerShell ($PROFILE に追記すると永続化)
empa completion powershell | Out-String | Invoke-ExpressionMCP モード (実験的)
empa mcp は CLI を stdio の Model Context Protocol サーバとして起動します。
MCP ホストから登録すると、保存済みの認証情報を使って account / receiver / cms / sites を
ツール経由で参照できます。
{
"mcpServers": {
"empa": {
"command": "empa",
"args": ["mcp", "--account", "acme"]
}
}
}
初回接続の前に empa login --account acme でログインしておきます。
既定では読み取り専用ツールのみが公開され、破壊的なツールは
--allow-write を付けたときだけ tools/list に現れます。
HTTP トランスポート (--transport http --listen 127.0.0.1:8765) は
認証境界を持たないため、ローカル開発の短時間利用に限定してください。
EMPA Sites も同じ枠組みでツール化されています。読み取り 17 本
(empa_sites_source_list/get, empa_sites_build_list/get,
empa_sites_deployment_list/get ほか) は既定で公開され、書き込み 26 本
(empa_sites_build_kick, empa_sites_deployment_create /
empa_sites_deployment_rollback, 各リソースの create / update / delete など)
は --allow-write 指定時のみ現れます。empa_sites_secret_* の
secret 値は CLI 同様 write-only で、いかなるツールの応答にも含まれません。
証明書 (#2561) は作成 (acm / imported / csr)・所有確認・CSR の取得と作り直し・CSR 方式の証明書のアップロード
(empa_sites_certificate_upload_csr、証明書と中間証明書だけ) を出しています。
秘密鍵を受け取るアップロード方式 (imported) のアップロードと、秘密鍵のエクスポートは MCP に出しません
(秘密鍵が AI の会話履歴に残るため)。imported のアップロードは CLI (--private-key-file) か画面で行います。
設定ファイル (config.toml)
| OS | パス |
|---|---|
| Linux / macOS | $XDG_CONFIG_HOME/empa/config.toml または ~/.config/empa/config.toml |
| Windows | %APPDATA%/empa/config.toml |
EMPA_CONFIG_DIR=<dir> で上書きできます。profile のスキーマ例:
default_profile = "default"
[profiles.default]
account_code = "acme"
environment = "prd"
default_app = "contact"
endpoint_account_template = "https://{account_code}.account.empa.jp"
endpoint_receiver = "https://{app_code}.receiver.empa.jp"
endpoint_cms = "https://{app_code}.cms.empa.jp"
endpoint_sites = "https://{app_code}.sites.empa.jp"
[update]
notify_on_start = false主な環境変数:
| 変数 | 意味 |
|---|---|
EMPA_ACCOUNT | 使用するアカウント (config の default_profile を上書き) |
EMPA_APP | 既定の app コード |
EMPA_CONFIG_DIR | config ディレクトリの上書き |
EMPA_STATE_DIR | state ディレクトリの上書き |
EMPA_SECRET_BACKEND | keyring / file (secret store を強制) |
EMPA_NO_UPDATE_CHECK | 起動時バージョン確認をスキップ |
トラブルシューティング
| 症状 | 対処 |
|---|---|
| ブラウザが開かない | login --no-browser で authorize URL を別マシンで開く |
unauthorized / 401 | empa login でトークンを更新 |
| keyring が無い環境 | 自動で file fallback (0600) に保管。EMPA_SECRET_BACKEND=file で強制可 |
| 出力形式を変えたい | --format json|yaml|table |
| 各コマンドの全フラグ | empa <command> --help が常に最新の正 |
このページはリリース時に apps/cli/README.md / docs/cli/ を元に生成・配置されています。詳細なユースケースはリポジトリの docs/cli/ を参照してください。