empa CLI マニュアル install.sh

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 分チュートリアル

  1. ログイン — ブラウザが開き、同意するとトークンが保管されます。 ブラウザを開けない環境 (SSH / WSL / Docker) では --no-browser を付けます。
    empa login --account acme
    empa login --account acme --no-browser   # 別マシンで authorize URL を開く
  2. 自分のセッションを確認
    empa whoami
    empa account show
  3. 利用可能な app を確認 — 出力の appCode を以降の --app で使うか、profile の default_app に保存します。
    empa account apps
    empa account apps --service receiver
    empa config set profiles.acme.default_app contact
  4. 最初の API 呼び出し — 出力は TTY なら table、pipe なら JSON が既定。 --format json|yaml|table で明示できます。
    empa receiver form list
    empa receiver form list --format json | jq '.[].slug'
  5. ヘルスチェック — 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-checkEMPA_NO_UPDATE_CHECK起動時のバージョン確認を 1 回スキップ
--profile <name>EMPA_PROFILE非推奨: --account のエイリアス

認証 / カタログ

コマンド用途
empa loginブラウザを開き PKCE フロー → トークン保管
empa logoutrefresh token を失効し、ローカルの secret を消去
empa whoami現在のセッション概要を 1 行で表示
empa profile list/show/use/add/removeprofile カタログの管理
empa config get/set/listconfig.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 showGET /api/account
empa account apps [--service receiver|cms]契約している app の一覧
empa me showGET /api/me
empa me update --display-name --emailPATCH /api/me
empa me password changeTTY 入力でパスワード変更
empa me tokens list/revokerefresh 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/updateFormAction (通知) の管理
# フォーム定義を 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.csv

cms

コマンド用途
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 uploadContentEntry の 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/kickgit 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/deletesite の CRUD (--source に紐付け)。slug は全テナントで一意・最大 59 文字。slugConflict: true は slug が他のサイトと重複していて自動割当ホストを配線できない状態で、site update <id> --slug で slug を変えると解消します
empa sites environment list/show/create/update/deleteenvironment の CRUD (--tier / --task-memory / --task-cpu / autoscale)。alias env
empa sites deployment list/show/create/rollbackimage を 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/deletesecret 参照。値は 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-validationTLS 証明書 (--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-csrimported / 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 statusaccount / 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 でプロセス内実行します。

  1. CloudFront の stable チャンネル manifest (stable/latest.json) を取得
  2. manifest のバージョンが empa version と一致すればスキップ
  3. OS/arch に対応するアーカイブと checksums.txt(.sigstore) を解決
  4. sigstore バンドルを端から端まで検証 (Fulcio 証明書チェーン / Rekor inclusion proof / GitHub Actions リリースワークフロー OIDC identity)
  5. アーカイブの 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-Expression

MCP モード (実験的)

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_DIRconfig ディレクトリの上書き
EMPA_STATE_DIRstate ディレクトリの上書き
EMPA_SECRET_BACKENDkeyring / file (secret store を強制)
EMPA_NO_UPDATE_CHECK起動時バージョン確認をスキップ

トラブルシューティング

症状対処
ブラウザが開かないlogin --no-browser で authorize URL を別マシンで開く
unauthorized / 401empa login でトークンを更新
keyring が無い環境自動で file fallback (0600) に保管。EMPA_SECRET_BACKEND=file で強制可
出力形式を変えたい--format json|yaml|table
各コマンドの全フラグempa <command> --help が常に最新の正

このページはリリース時に apps/cli/README.md / docs/cli/ を元に生成・配置されています。詳細なユースケースはリポジトリの docs/cli/ を参照してください。