Proof CLI (unofficial)

Proof CLI

Proof API と連携するための非公式コマンドラインインターフェースです。Proof CLI では、統合されたインターフェースを通じて、Business、Real Estate、SCIM API を利用できます。

これはアルファ版の製品であり、そのように扱う必要があります。Proof の公式製品ではありません。

インストール

ビルド済みバイナリ

# macOS / Linux: downloads the latest release for your OS and CPU into the current directory
curl -sL "https://github.com/tsarlewey/proof-cli/releases/latest/download/proof_$(uname -s | tr A-Z a-z)_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz proof
./proof version

Windows 用の ZIP ファイルとチェックサムは、Releases ページにあります。

Go でインストール

go install github.com/tsarlewey/proof-cli@latest

ソースからインストール

git clone https://github.com/tsarlewey/proof-cli.git
cd proof-cli
go build -o proof
./proof --help

AI エージェントでの使用

Claude Code プラグイン（利用方法のスキルと MCP サーバーが含まれています。proof を PATH に設定する必要があります）：

/plugin marketplace add tsarlewey/proof-cli
/plugin install proof@proof

あらゆる MCP クライアントで使えるMCP サーバー。proof mcp は、すべての API コマンドを stdio 経由のツールとして公開し、読み取り専用または破壊的操作として注釈を付けます。

claude mcp add proof -- proof mcp               # Claude Code
claude mcp add proof -- proof mcp --read-only   # only tools that don't change anything

ほかのクライアントでは、proof mcp コマンドを実行してください。認証情報は CLI と同じ方法で読み込まれます（PROOF_API_KEY または proof config）。

ローカルに何もインストールせずに使える Docker。イメージは proof mcp を実行し、MCP Registry に io.github.tsarlewey/proof-cli として登録されています。

docker run -i --rm -e PROOF_API_KEY -e PROOF_API_ENDPOINT=https://api.fairfax.proof.com ghcr.io/tsarlewey/proof-cli

イメージ名の後に指定した引数は proof mcp に渡されます（例：--read-only）。PROOF_API_ENDPOINT はどのモードでも設定済みのエンドポイントを上書きします。本番環境では設定しないでください。

シェルを使うエージェントは、skills/proof/SKILL.md を参照してください。出力は JSON 形式です（コンパクトにするには --pretty=false を指定）。API エラーが発生すると、レスポンス本文を stderr に出力して終了コード 1 で終了します。テスト中はサンドボックスを指定してください：proof config set-endpoint https://api.fairfax.proof.com。

はじめに

1. 設定

CLI を使用する前に、API キーを設定する必要があります。

# Set your API key
proof config set-api-key YOUR_API_KEY

# Or set via environment variable
export PROOF_API_KEY=YOUR_API_KEY

# Verify your configuration
proof config get

API キーを取得するには、API Usage を利用できるアカウントが必要です。こちらから取得できます：https://www.proof.com/pricing#business

アカウントを作成してアップグレードした後、https://dev.proof.com/docs/api-keys でキーを設定してください。

OAuth 2.0 認証

CLI は、安全な API 認証のために OAuth 2.0 クライアントクレデンシャルフローをサポートしています。

# Configure OAuth credentials
proof config set-oauth <client-id> <client-secret> [--scope="read write"]

# Test OAuth authentication
proof config test-oauth

# Disable OAuth (fallback to API key)
proof config disable-oauth

OAuth トークンは、有効期限が切れる前に自動的に更新されます（5 分の余裕を確保）。

2. 基本的な使い方

CLI は、次の 3 つの主要な API グループで構成されています。

• business - Business API の操作（トランザクション、ドキュメント、Webhook、公証人など）
• real-estate - Real Estate／Mortgage API の操作
• scim - ユーザー管理用の SCIM API 操作

# Get help for any command
proof --help
proof business --help
proof real-estate --help
proof scim --help

API リファレンス

Business API

Business API は、トランザクションとドキュメントを包括的に管理する機能を提供します。

トランザクション

# List all transactions
proof business transactions list

# List with filtering
proof business transactions list --limit 10 --status completed

# Get a specific transaction
proof business transactions get <transaction-id>

# Create a new transaction
proof business transactions create \
  --email "[email protected]" \
  --first-name "John" \
  --last-name "Doe" \
  --document "/path/to/document.pdf" \
  --name "Contract Signing" \
  --draft

# Multiple documents, scheduled notary meeting, and a redirect
proof business transactions create \
  --email "[email protected]" \
  --document "/path/to/deed.pdf" \
  --document "/path/to/rider.pdf" \
  --notary-meeting-time "2026-09-02T15:30:00Z" \
  --allowed-notary-states "CA,NY" \
  --notary-note "Verify the property address" \
  --payer sender \
  --idv-use-case ACCOUNT_RECOVERY \
  --recipient-details-config "name=locked" \
  --redirect-url "https://example.com/done"

# Multiple signers, from a JSON file holding an array of signer objects
# (max 10, each needs at least an email). --email stays the primary signer.
proof business transactions create \
  --email "[email protected]" \
  --document "/path/to/document.pdf" \
  --signers-file ./signers.json

# Replace a draft transaction (PUT) -- anything you omit reverts to default
proof business transactions update <transaction-id> \
  --name "Contract Signing (revised)" \
  --expiry "2026-09-08T10:00:00Z"

# Change individual fields and leave the rest alone (PATCH)
proof business transactions patch <transaction-id> --expiry "2026-09-15T10:00:00Z"

# Reorder documents already attached to a draft
proof business transactions patch <transaction-id> \
  --document-order "doc_abc123=1" \
  --document-order "doc_def456=2"

# See the full parameter set
proof business transactions create --help

# Activate a draft transaction
proof business transactions activate <transaction-id>

# Delete a transaction
proof business transactions delete <transaction-id>

# Cancel a transaction
proof business transactions cancel <transaction-id>

ドキュメント

# Add a document to a transaction
proof business documents add <transaction-id> /path/to/document.pdf \
  --filename "Contract.pdf" \
  --requirement "esign" \
  --esign-required

# Apply a specific template instead of automatic matching
proof business documents add <transaction-id> /path/to/document.pdf --template-id <template-id>

# Get a document
proof business documents get <transaction-id> <document-id>

# Get document as hosted URL (after completion)
proof business documents get <transaction-id> <document-id> --encoding uri

# Delete a document
proof business documents delete <document-id>

Webhook

# List webhooks (v2)
proof business webhooks list

# Get webhook details
proof business webhooks get-v2 <webhook-id>

# Create a webhook
proof business webhooks create \
  --url "https://example.com/webhook" \
  --name "Transaction Updates" \
  --events "transaction.created,transaction.completed"

# Update a webhook
proof business webhooks update <webhook-id> \
  --url "https://new-url.com/webhook"

# Delete a webhook
proof business webhooks delete <webhook-id>

# Get webhook events
proof business webhooks events <webhook-id>

# List available event subscriptions
proof business webhooks subscriptions

公証人

# List notaries
proof business notaries list

# List notaries by state
proof business notaries list --state CA

# Get notary details
proof business notaries get <notary-id>

# Create a notary
proof business notaries create \
  --email "[email protected]" \
  --first-name "Jane" \
  --last-name "Smith" \
  --state "CA"

# Delete a notary
proof business notaries delete <notary-id>

テンプレート

# List document templates
proof business templates list

# List with pagination
proof business templates list --limit 50 --offset 100

コストセンター

# List cost centers, then attribute a transaction with --cost-center-id
proof business cost-centers list
proof business transactions create --email [email protected] --cost-center-id <id>

紹介

# Create a referral campaign
proof business referrals create \
  --name "Partner Referrals" \
  --cover-payment \
  --redirect-url "https://example.com/signup"

# Generate a referral code
proof business referrals generate-code <campaign-id> \
  --expires-at "2024-12-31T23:59:59Z"

インテグレーション

# Create an Adobe integration
proof business integrations create \
  --name "ADOBE" \
  --org-id "your-org-id" \
  --account-id "adobe-account-id" \
  --environment "production"

# Create a DocuTech integration
proof business integrations create \
  --name "DOCUTECH" \
  --org-id "your-org-id"

Real Estate API

Real Estate API は、住宅ローンおよび不動産取引の管理に特化しています。

トランザクション

# List real estate transactions
proof real-estate transactions list

# List with filtering
proof real-estate transactions list --status "in_progress" --limit 20

# Get transaction details
proof real-estate transactions get <transaction-id>

# Create a transaction
proof real-estate transactions create \
  --type "purchase" \
  --file-number "RE-2024-001" \
  --loan-number "LN-2024-001"

# Place an order for a transaction
proof real-estate transactions place-order <transaction-id>

# Cancel a transaction
proof real-estate transactions cancel <transaction-id>

テンプレート

# List templates
proof real-estate templates list

コストセンター

proof real-estate cost-centers list
proof real-estate transactions create --cost-center-id <id>

ドキュメント

# List documents
proof real-estate documents list <transaction-id>

# Get document details
proof real-estate documents get <document-id>

# Upload a document
proof real-estate documents upload <transaction-id> /path/to/document.pdf \
  --type "purchase_agreement" \
  --external-id "PA-001"

Webhook

# List real estate webhooks
proof real-estate webhooks list

# Create a webhook
proof real-estate webhooks create "https://example.com/re-webhook" \
  --subscriptions "transaction.created,document.uploaded"

住所確認

# Verify an address
proof real-estate verify-address \
  --line1 "123 Main St" \
  --city "San Francisco" \
  --state "CA" \
  --postal-code "94102"

SCIM API

SCIM API は、標準化されたユーザー管理機能を提供します。

ユーザー

# List users in an organization
proof scim users list <organization-id>

# List with pagination
proof scim users list <organization-id> --start-index 1 --count 25

# Get user details
proof scim users get <organization-id> <user-id>

# Create a user
proof scim users create <organization-id> \
  --username "[email protected]" \
  --given-name "John" \
  --family-name "Doe" \
  --email "[email protected]" \
  --active

# Update a user (full replacement)
proof scim users update <organization-id> <user-id> \
  --username "[email protected]" \
  --given-name "Jane"

# Patch a user (partial update); --operation is repeatable, format op:path[:value]
proof scim users patch <organization-id> <user-id> \
  --operation 'replace:active:false'

# Delete a user
proof scim users delete <organization-id> <user-id>

スキーマ

# Get user schema
proof scim schemas user <organization-id>

# Get service provider configuration
proof scim schemas service-provider-config <organization-id>

# Get resource types
proof scim schemas resource-types <organization-id>

セキュリティイベント API

組織の OCSF 形式のセキュリティイベントログを読み取ります。

# List recent security events
proof logs list

# Page through results
proof logs list --limit 100
proof logs list --cursor <next_cursor-from-previous-response>

# Filter
proof logs list --since 2026-01-01T00:00:00Z
proof logs list --class-uid 1001 --severity-id 3

証明書 API

組織の証明書を発行、使用、失効します。

# List certificates
proof certificates list --limit 25 --offset 0

# Get one certificate
proof certificates get <certificate-id>

# Issue a certificate with a Proof-generated key
proof certificates create \
  --common-name "Acme Signing Authority" \
  --profile organization_authenticity_al2

# Issue a certificate from your own CSR
proof certificates create-from-csr --csr "$(cat request.pem)"

# Sign base64-encoded SHA256 digests (--digest is repeatable, max 25)
proof certificates sign <certificate-id> --digest "BOGQnhPlcpXqM7fAH6tvFPI4QOXsIyXMiBKtFpblmjU="

# Revoke
proof certificates revoke <certificate-id> --reason "key compromise"

検証可能なクレデンシャル API

エンドユーザーに検証可能なクレデンシャルの提示を要求します。このエンドポイントはブラウザーへのリダイレクトであり、サーバー間の呼び出しではありません。CLI はエンドユーザーに送る URL を表示しますが、その URL へのリダイレクトは行いません。

# Fragment mode: the vp_token comes back on your redirect URI
proof credentials authorize-url \
  --client-id <oauth-client-id> \
  --response-mode fragment \
  --redirect-uri https://app.example.com/callback \
  --scope "openid" \
  --login-hint [email protected] \
  --nonce "$(openssl rand -hex 16)" \
  --state "$(openssl rand -hex 8)"

# direct_post mode: Proof POSTs the vp_token to your response URI
proof credentials authorize-url \
  --client-id <oauth-client-id> \
  --response-mode direct_post \
  --response-uri https://app.example.com/vp \
  --scope "openid" \
  --login-hint [email protected] \
  --nonce "$(openssl rand -hex 16)"

fragment モードでは --redirect-uri が必須で、direct_post モードでは指定できません。--response-uri はその逆です。両方の URI を OAuth Application に登録する必要があります。

例

CLI には、一般的なワークフローを紹介するコマンド例が含まれています。

# List all available examples
proof example --help

# Business API examples
proof example business-transactions     # List business transactions
proof example business-notary          # Create a notary

# Real Estate API examples
proof example real-estate-transactions  # List real estate transactions
proof example verify-address           # Verify an address

# SCIM API examples
proof example scim-users <org-id>       # List SCIM users
proof example scim-schema <org-id>      # Get SCIM user schema

設定

CLI の設定は ~/.proof-cli/ に保存されます。

• config.json - メイン設定ファイル
• api_key - API キー（権限 0600）

設定オプション：

• endpoint - API エンドポイントの URL
• timeout - リクエストのタイムアウト（秒）

# View current configuration
proof config get

# Set API endpoint
proof config set-endpoint "https://api.proof.com"

# Set request timeout
proof config set-timeout 30

# Set API key
proof config set-api-key "your-api-key"

グローバルフラグ

すべてのコマンドで、次のグローバルフラグを使用できます。

• --pretty - JSON 出力を整形して表示します（デフォルト：true）
• --verbose - 追加のデバッグ出力を表示します
• --help - ヘルプ情報を表示します

環境変数

• PROOF_API_KEY - 認証用 API キー
• PROOF_ENDPOINT - デフォルトの API エンドポイントを上書きします
• PROOF_TIMEOUT - リクエストのタイムアウト（秒）

エラー処理

CLI は詳細なエラーメッセージを表示し、標準の終了コードを使用します。

• 0 - 成功
• 1 - 一般エラー（API エラー、無効な引数など）

開発

ソースからのビルド

git clone https://github.com/tsarlewey/proof-cli.git
cd proof-cli
go mod download
go build -o proof

Makefile のターゲット

このプロジェクトでは、一般的な開発タスク用に Makefile を提供しています。

make build          # Build the ./proof binary
make install        # Install the CLI via go install
make fmt            # Run go fmt
make vet            # Run go vet
make test           # Run all tests
make test-race      # Run all tests with -race
make coverage       # Run tests with coverage profile
make check          # fmt + vet + build + test-race
make clean          # Remove the built binary
make smoke          # Run shell smoke tests against live API
make smoke-go       # Run Go smoke tests (build-tag smoke)
make smoke-write    # Run shell write smoke tests (PROOF_SMOKE_WRITE=1)
make smoke-write-go # Run Go write smoke tests (build-tag smoke_write)

SDK のソース

生成された Go SDK クライアントは、専用リポジトリ github.com/tsarlewey/proof-sdk-go に移動しました。この CLI は通常の Go モジュール依存関係としてインポートします、上流の OpenAPI 仕様の変更後にクライアントを再生成する必要がある場合は、SDK リポジトリ内で作業してください。生成ツールチェーン（OpenAPI 仕様、oapi-codegen の設定、前処理スクリプト、make regenerate）もそちらに移動しました。

この CLI で新しい SDK リリースを取り込むには、次の手順を実行します。

go get github.com/tsarlewey/proof-sdk-go@<new-version>
go mod tidy
make check

コマンドの追加または更新

CLI コマンドは cmd/ にあります（API サーフェスごとに 1 ファイル）。Cobra を使って構築されています。各コマンドの Run クロージャーは、cmd/root.go のファクトリーヘルパー（getBusinessClient、getRealEstateClient、getSCIMClient）を通じて、生成された SDK クライアントのメソッドを呼び出します。ファクトリーは SDK リポジトリの common.AuthenticatedDoer で SDK クライアントをラップし、すべてのリクエストに OAuth ベアラートークンまたは API キーを付与します。

cmd/root.go の共有ヘルパー：

• initializeForAPICall — クライアントを遅延初期化します。API を呼び出すすべてのコマンドで PreRun として使用されます。
• PrintResponse / PrintVerbose — オプションの整形表示と色付けに対応したレスポンス出力です。
• parseDateFlag — 日付フラグの値（省略可能）を解析します。解析に失敗すると、明確なメッセージを表示して終了します。
• isSuccess — 2xx ステータスコードを確認します。
• checkAPIStatus — SDK 呼び出しのたびに、API が 2xx 以外のレスポンスを返した場合は、本文を標準エラー出力に表示して 1 で終了します。

SDK 呼び出しのエラーは、トランスポートエラーの場合は utils.HandleError(err, "action phrase") に、アプリケーションレベルの HTTP エラーの場合は checkAPIStatus(resp.StatusCode(), resp.Body, "action phrase") に集約されます。どちらも 1 で終了します。

サポート

問題の報告や機能リクエストについては、GitHub リポジトリをご覧ください。

ライセンス