uzuctl (UZU 内部 CLI)

UZU / mdms_jp バックエンドを CLI / AI エージェントから安全に叩くための開発者向け CLI。gcloud auth login 相当の体験を持ち、Firebase 認証の GraphQL と AlloyDB / Cloud SQL の両方を 1 ツールで触れる。

設計の全体像は Linear プロジェクト uzuctl: AI 時代の CLI 認証基盤 を参照。ソースとより詳細な README は go/uzuctl/ にある。

インストール

ワンライナーで ~/.local/bin/uzuctl を入れる:

curl -fsSL https://uzuctl.uzu-asset.com/install.sh | sh

• 配置先を変えたいときは UZUCTL_INSTALL_DIR=/usr/local/bin を頭に付ける
• zsh 補完 (~/.zsh/completions/_uzuctl) も自動生成される。fpath 追加と compinit は手動で ~/.zshrc に書く必要があるので、初回はインストーラの最後に出る案内に従う
• 配信は gzip 圧縮済みバイナリ (uzuctl-<os>-<arch>.gz)。展開はインストーラ / 自己更新が肩代わりする

自己更新

uzuctl update --check     # 差分があるかだけ表示
uzuctl update             # その場で最新版に置換 (atomic rename)
uzuctl update --force     # 同 SHA / dev ビルドでも強制 download

https://uzuctl.uzu-asset.com/cli/version.json の SHA と現在の uzuctl --version を比較して差分があれば置換する。os.Rename による atomic 置換のため更新中にプロセスが死ぬ心配はない (Windows は未対応)。

初回セットアップ

# 1. Firebase 認証 (refresh_token は OS keychain に保存される)
uzuctl auth login --env dev

# 2. GraphQL を叩いてみる
uzuctl gql query '{ me { id email } }'

# 3. (DB を触りたいなら) gcloud ADC も用意
gcloud auth application-default login

uzuctl auth login (Firebase) と gcloud auth application-default login (Cloud SDK) は 完全に独立:

• GraphQL を叩く → Firebase auth (uzuctl auth login) のみ必要
• DB を直接叩く → gcloud ADC のみ必要
• 両方やりたい → 両方ログイン

dev / stg / prd を行き来したいときは環境ごとに auth login を済ませるか、uzuctl config set environment <env> でアクティブ環境を切り替える。

コマンド一覧

uzuctl auth login [--env <env>]      # PKCE 認証 (refresh_token を keychain へ保存)
uzuctl auth list                     # 認証済み環境一覧
uzuctl auth logout [--env <env>] [--all]
uzuctl auth print-access-token       # id_token を stdout に出力 (CI / curl 用)

uzuctl gql query <query>             # GraphQL クエリ
uzuctl gql mutation <query>          # GraphQL ミューテーション
uzuctl gql schema [--format sdl|json|raw]   # introspection 取得

uzuctl db exec <sql>                 # AlloyDB / Cloud SQL に IAM 認証で SQL 実行
uzuctl db register-ip --env <e> --db <db>   # 手元 IP を AlloyDB allowlist に追加

uzuctl config set <key> <value>      # 設定値を更新 (~/.config/uzuctl/config.toml)
uzuctl config get <key>
uzuctl config list

uzuctl update [--check] [--force]    # 最新バイナリで自身を置換
uzuctl version                       # バージョン情報
uzuctl completion <shell>            # シェル補完を出力

主要レシピ

GraphQL クエリ

# UZU バックエンド (active target が uzu の場合)
uzuctl gql query '{ me { id email } }'

# mdms_jp バックエンドへ一時切替
uzuctl gql --target mdms_jp query '{ shopGroups { id name } }'

# 環境を一時切替
uzuctl gql --env stg query '{ ... }'

# variables 付き mutation
uzuctl gql mutation 'mutation Foo($id: ID!) { foo(id: $id) { ok } }' --vars '{"id":"abc"}'

# stdin / ファイル
uzuctl gql query -f path/to/query.graphql
echo '{ me { id } }' | uzuctl gql query -

# 出力を生 JSON (整形なし) に
uzuctl gql query '{ me { id } }' --output raw

# curl などで再利用するために id_token だけ取りたい
curl -H "Authorization: Bearer $(uzuctl auth print-access-token --env dev)" \
  https://dev.graph.backend.app.uzu.one/graphql

GraphQL スキーマ取得

uzuctl gql schema                 # 現在の env/target を SDL で出力
uzuctl gql schema --target mdms_jp
uzuctl gql schema --format json   # introspection 結果を pretty JSON で

サーバ側の introspection は admin (社員) のみ有効化されているため、uzuctl auth login で取った id_token が admin として認められる必要がある。

DB に SQL を実行

uzuctl auth login (Firebase) とは独立して gcloud ADC + IAM 認証 で動く。GCP 側に IAM ユーザーとして登録されている必要がある (uzuctl 側で IAM の追加付与はしない)。

# SELECT (env を問わずプロンプト無し)
uzuctl db exec --env prd --db app "SELECT count(*) FROM users"

# stdin / ファイル入力
echo "SELECT * FROM scenarios LIMIT 5" | uzuctl db exec --env prd --db app -
uzuctl db exec --env stg --db app -f migration.sql

# 出力フォーマット (default は psql 風の整列表)
uzuctl db exec --env prd --db app --output json "SELECT id, email FROM users LIMIT 5"
uzuctl db exec --env prd --db app --output csv  "SELECT id, email FROM users LIMIT 5"

# DML/DDL は stg/prd で yes タイプ要求、dev は警告のみ
uzuctl db exec --env prd --db app "DELETE FROM users WHERE id=42"
# => 確認プロンプト → "yes"

# CI / スクリプトから明示的にスキップ
uzuctl db exec --env prd --db app --dangerously-skip-confirmation "UPDATE ..."

環境 \ 種別	ReadOnly	SideEffect (INSERT/UPDATE/DELETE/MERGE/COPY)	SchemaChange (CREATE/DROP/ALTER/GRANT/REVOKE/TRUNCATE/...)
dev	プロンプト無し	警告表示のみ	警告表示のみ
stg	プロンプト無し	yes タイプ要求	yes タイプ要求
prd	プロンプト無し	yes タイプ要求	yes タイプ要求 + DDL 警告強調

接続先インスタンス (2026-05 時点):

env	種別	インスタンス
dev	Cloud SQL	uzu-dev:asia-northeast1:uzu-postgresql
stg	AlloyDB	uzu-stg / clusters/uzu-shared
prd	AlloyDB	app は uzu-app cluster、それ以外 (mdms_jp / uzutokyo) は uzu-shared cluster

手元 IP の自動登録 (AlloyDB)

AlloyDB の authorized_external_networks に手元 IP が無いと接続できないが、db exec は 15 秒で fast-fail してから自動で db register-ip を呼んで再試行する。普段は意識する必要はない。

明示的に登録だけ行いたいとき:

uzuctl db register-ip --env stg --db app
uzuctl db register-ip --env prd --db app           # uzu-app cluster
uzuctl db register-ip --env prd --db mdms_jp       # uzu-shared cluster
uzuctl db register-ip --env stg --db app --dry-run # 差分だけ確認

CI で自動登録を抑止したいときは db exec に --no-auto-register-ip を付ける。

設定の編集

設定ファイル ~/.config/uzuctl/config.toml:

[core]
environment = "dev"
account = "you@example.com"
target = "uzu"

uzuctl config set environment stg
uzuctl config set target mdms_jp
uzuctl config get environment
uzuctl config list

core. プレフィックスは省略可。environment は dev|stg|prd、target は uzu|mdms_jp のみ受け付ける。targets.<name>.graphql_endpoint_* は CLI から触らせていないので必要なら直接 config.toml を編集する。

トラブルシュート

gcloud ADC が見つかりませんでした (db exec)

gcloud auth application-default login

Cloud SQL IAM user authentication failed (db exec, dev)

dev Cloud SQL では cloudsql.iam_authentication=on flag が必要 + IAM ユーザー登録が必要。stg / prd の AlloyDB は社員が事前登録済みなのでこの問題は発生しない。dev で詰まったら #team-engineering で相談。

IAM ユーザーが未登録の可能性があります (db exec, stg/prd)

入社直後など allowlist に email が無い場合はエラー文に出るコマンドで登録 (admin 権限が必要):

gcloud alloydb users create <email> --cluster=<cluster> --region=asia-northeast1 --project=<project> --type=IAM_BASED

未登録時は #team-engineering で登録依頼するのが早い。

prepared statement already exists (SQLSTATE 42P05)

AlloyDB 前段の pooler と pgx の prepared statement cache の衝突が原因。uzuctl 0.1.x 以降は simple protocol を強制しているので発生しない。発生するなら uzuctl update で更新する。

task uzuctl:run で yes プロンプトが出ない

go-task の output: prefixed がインタラクティブ入力を奪っているため。taskfiles/uzuctl.yaml で interactive: true を指定すれば直結する。手元の checkout が古い場合は git pull してから。

uzuctl update で 404

旧バージョンのバイナリ URL は非 gzip だが、現在は .gz 配信のみ。一度だけ curl -fsSL https://uzuctl.uzu-asset.com/install.sh | sh で再インストールすると最新の自己更新ロジックを持った uzuctl になる。

認証情報の保存場所

OS	場所
macOS	Keychain (service=uzuctl, account=<env>:<email>)
Linux	Secret Service (gnome-keyring 等)
Windows	Credential Manager
keychain が使えない場合	~/.config/uzuctl/credentials/<env>/<email>.json (0600)

uzuctl auth logout でクライアント側の credentials を消せるが、Firebase の refresh_token をサーバ側で revoke するには Admin SDK が必要なため、不正流出を確実に殺したい場合は別途 Firebase Console から対応する必要がある。

関連リンク

• go/uzuctl/README.md — 詳細リファレンス (実装ノート含む)
• Linear プロジェクト — 設計判断の履歴
• Cloudflare Workers 配信 (uzuctl.uzu-asset.com) — 配布インフラ