AtoA

Atoa CLI

Atoa 決済 API 用のファーストパーティ製コマンドラインインターフェイスです。ターミナルから加盟店、決済、返金、Webhook、銀行フィード、入金を管理できます。スクリプトから実行でき、安全で、sandbox と production の両方で一貫して動作します。

ドキュメント： Atoa Docs

atoa login                                  # pair this machine with your Atoa account
atoa payments create --amount 10.05 --orderId order-001 --customerId cust_123
atoa webhooks trigger PAYMENTS_STATUS       # fire a fake event at your sandbox URL

---

インストール

npm install -g @atoapayments/atoa-cli

Node.js 20 以降が必要です（node --version）。

確認方法：

atoa --version

Sandbox と production

同じバイナリで sandbox と production の両方に接続できます。コマンドの対象環境は --env で選ぶか、プロファイルごとにデフォルトを設定します（atoa profile set env=production）。トークンと環境の組み合わせが間違っていると、最初の認証済み呼び出しで 401 が表示されます。atoa whoami を実行して、どの環境に対して認証されているかを確認してください。

---

クイックスタート

# 1. Log in via your browser (recommended)
atoa login

# 2. Confirm
atoa whoami

# 3. Try a real call
atoa stores list
atoa payments create --amount 10.05 --orderId test-001 --customerId cust_123 --redirectUrl https://example.com

認証情報は ~/.atoa/auth/ 配下の所有者のみ読み取り可能な（0600）JSON ファイルに保存されます。JWT セッションは session.json に、SDK API キーは secret_key.json に保存されます。ファイルは平文で保存されます（AWS／gcloud／Stripe の CLI と同様、OS のキーチェーンは使用しません）。これにより、同じマシン上の自動化処理やコーディングエージェントから読み取れます。認証情報が .env ファイルやシェルの履歴に保存されることはありません。

---

プロファイルと環境

1 台のマシンに、複数の加盟店（プロファイル）と、両方の環境（sandbox ＋ production）の認証情報を保持できます。CLI はそれらを分離して管理するため、テストセッション中に誤って本番用のキーが実行されることはありません。注意：各バイナリが接続するサーバーは 1 つだけなので、認証情報に接続できるかどうかは、インストールしたビルドにも左右されます（上記を参照）。

atoa profile list                  # see every profile + which envs are configured
atoa profile show                  # detailed metadata for the active profile
atoa profile use acme              # switch active profile
atoa profile set env=production    # set the default env for the active profile (prompts)
atoa profile rename acme acme-uk   # rename + move the stored credentials
atoa profile delete old-merchant   # remove profile + its JWT session and SDK keys
atoa whoami --env production       # query against a specific env without switching the default

ブラウザーでのログイン（atoa login）は環境に依存しません。プロファイルごとに 1 つの JWT セッションが、sandbox と production の両方で使えます。 defaultEnv は、SDK／データコマンドがデフォルトで対象とする環境のみを決定します。

---

サインイン

ブラウザーフロー（推奨）

atoa login      # opens the Atoa dashboard grant page in your default browser

atoa login では --env は指定しません。ブラウザー認証は単一の認証バックエンドに対して行われるため、取得した JWT セッションは sandbox と production の両方で使えます。プロファイルは環境ごとに分かれません。

処理の流れ：

1. CLI が PKCE ペアとランダムな state 値を生成し、ランダムなポートで一時的な localhost サーバーを起動します。
2. デフォルトのブラウザーで Atoa ダッシュボードの認証ページ（/auth/extension-callback）を開きます。
3. ブラウザーでリクエストを承認します。
4. ダッシュボードから、ワンタイムコードとともに http://127.0.0.1:<port>/callback にリダイレクトされます。
5. CLI がコードを JWT アクセストークンとリフレッシュトークンに交換します（サーバー側で PKCE を検証します）。
6. アカウントが複数のビジネスに属している場合は、選択を求められます（対話型ターミナルのみ。非対話型のログインは完了しますが、その後 atoa business use <id> を実行するよう求められます）。
7. プロファイルが作成（または更新）され、JWT ペアが ~/.atoa/auth/session.json に保存されます（所有者のみ読み取り可能、0600）。

atoa login の実行には、対話型ターミナル（TTY）と同じマシン上のデスクトップブラウザーが必要です。ヘッドレス環境や CI からログインする方法はありません。CI では、ワークステーション上で認証情報を用意し、~/.atoa/auth/ のファイルをランナーから利用できるようにしてください（CI／自動化を参照）。

SDK キーの発行

SDK／データコマンド（payments、refunds、…）を使うには、SDK API キーが必要です。ログイン後に明示的に作成してください。

atoa keys create --env sandbox    # mints a revocable SDK key, writes it to secret_key.json

apiSecret は一度だけ表示されます。すぐに保存してください。ビジネスの管理者ロールが必要です。

---

2 種類の認証情報

CLI は、プロファイルと環境ごとに、独立した 2 種類の認証情報に対応しています。

atoa login (browser)
      │
      ├─► JWT access token  ──► account-management commands (v1 API)
      │   JWT refresh token      business, sessions, keys, staff, roles,
      │                          kyb, payment-links, bank, stores,
      │                          addons, comms, custom-branding,
      │                          custom-sms, direct-debit
      │
      └─► SDK API key (optional, via `atoa keys create`)
              ──► payments/data commands (legacy API)
                  payments, refunds, customers, card-on-file,
                  webhooks, bank-feed, payouts, institutions,
                  get, post, delete

atoa login を実行すると、常に JWT ペアが発行されます。SDK キーは任意で、atoa keys create を使えばいつでも追加できます。

認証情報は ~/.atoa/auth/ 配下の所有者のみ読み取り可能な（0600）2 つの JSON ファイルに保存されます。

ファイル	内容	キーの単位
session.json	JWT アクセストークンとリフレッシュトークン（ブラウザーログイン）	プロファイルのみ — ブラウザーログインは 1 つの認証バックエンドを使用するため、環境に依存しません
secret_key.json	SDK API キー（atoa keys create）	プロファイル ＋ 環境

どのコマンドにどのログインが必要か

認証が必要	コマンド
JWT（ブラウザーログイン）	business list/use, sessions list/revoke, keys create/list, kyb status/link, kyb card status/link, staff *, roles *, payment-links create/get/delete, bank list/get/add/delete, stores *, addons *, comms list/set, custom-branding get/set/reset, custom-sms list/set/delete, direct-debit status/setup
SDK キー（atoa keys create）	payments *, refunds *, customers *, payment-methods *, card-on-file *, webhooks *, bank-feed *, payouts *, institutions list, get, post, delete
どちらでも可	whoami, keys revoke/regenerate
不要（独自に認証）	signup（アカウントとセッションを作成します）、completion、profile *、reset

JWT が必要なコマンドは、アクティブなプロファイルに SDK キーしかなく、JWT セッションがない場合、明確なメッセージを表示してエラーになります。JWT セッションを取得するには atoa login（ブラウザー）を実行してください。SDK／データ関連のコマンドを使う場合は、atoa keys create で SDK キーを作成してください。

---

新しいコマンドのリファレンス

アカウント管理（business、sessions）

atoa business list                      # list businesses on this account; marks the active one
atoa business use <businessId>          # switch the active business for /v1 API calls
atoa sessions list                      # list active CLI sessions for this account
atoa sessions revoke <deviceId>         # revoke a session (--yes to skip confirmation)

SDK キー管理（keys create、keys list）

これらのコマンドは、既存の keys revoke／keys regenerate コマンドを拡張するものです。

atoa keys create                        # create a new SDK API key (jwt mode; prompts for a label)
atoa keys create --name "CI server"     # label the key non-interactively
atoa keys list                          # list SDK keys for this account (never shows secrets)

KYB（kyb）

atoa kyb status                         # get the KYB verification status for this business
atoa kyb link                           # open the KYB form in the browser (prints the URL too)
atoa kyb card status                    # card-payment application status + what blocks it
atoa kyb card link                      # open the card-payment application form

スタッフとロール（staff、roles）

staff add と staff invite は、名前が異なるだけで同じコマンドです。TTY では識別子を省略すると CLI がプロンプトを表示し、レコードの現在値があらかじめ入力されます。

atoa staff list                         # list staff members for this business
atoa staff add \
  --firstName Alice --lastName Smith \
  --email [email protected] \
  --role <roleId>                       # add a new staff member
atoa staff add … --store <storeId>      # restrict to one or more stores (repeatable flag)
atoa staff update <userId>              # edit name, email, phone, role or permitted stores
atoa staff delete <userId> --yes        # remove a staff member from the business
atoa roles list                         # list available roles for this business
atoa roles permissions                  # permission catalogue: id, name, category, requires
atoa roles add --name "Shift lead"      # create a role; prompts for permissions
atoa roles add --name "Shift lead" --permission <id>   # repeat --permission for several
atoa roles update <roleId>              # edit name, description or permissions
atoa roles delete <roleId> --yes        # delete a role

--permission には権限の ID を指定します。権限 ID は atoa roles permissions で一覧表示できます。ほかのすべての表示では名前のみが表示されます。権限はほかの権限に依存する場合があります。権限を選択すると、必要な権限が自動的に付与され、追加された権限が CLI に表示されます。

銀行口座（bank）

atoa bank list                          # list bank accounts for the active business
atoa bank add                           # interactive: pick bank, enter details, verify via OTP
atoa bank add --sortCode 123456 --accountNumber 12345678 \
  --accountHolderName "<account holder name>"

# Non-interactive. If a one-time code is required, the first run exits with code 9 having sent it:
atoa bank add --bankName "<bank name>" --sortCode 123456 \
  --accountNumber 12345678 --accountHolderName "<account holder name>" --output json
#   → exit code 9: "An OTP was sent to your registered contact. Re-run with --otp <code>"
atoa bank add <same flags> --otp <code> --output json        # → exit code 0
atoa bank get <bankAccountId>           # get a bank account by id
atoa bank delete <bankAccountId> --yes  # remove a bank account

事業者の最初の銀行口座は、自動的にメイン口座になります。--setPrimary を指定すると、Atoa が決済に使用する口座が切り替わり、すでに口座が関連付けられているすべての拠点の関連付け先も変更されます。そのため、請求先口座を変更する場合にのみ指定してください。

決済リンク（payment-links）

--amount はポンド単位です（例：10.50）。ペンス単位ではありません。--store-id は必須です。

atoa payment-links create --amount 10.50 --store-id <id>                  # create a link
atoa payment-links create --amount 10.50 --store-id <id> --notes "Inv 42" # notes max 30 chars
atoa payment-links get <linkId> --store-id <id>                           # fetch a link + status
atoa payment-links delete <linkId> --store-id <id>                        # delete a link

ストア（stores）

atoa stores list                        # list stores for this business
atoa stores get <storeId>               # get a store by ID
atoa stores add                         # interactive: name, address, postcode
atoa stores add --locationName "Soho" --addressLine1 "12 Dean St" \
  --cityOrTown London --addressPostalCode W1D3RP
atoa stores update <storeId>            # prompts with the store's current values prefilled
atoa stores link-bank <storeId> --bank <bankAccountId>  # link a bank account to a store
atoa stores image ./logo.png --storeId <storeId>        # upload/replace store logo (PNG/JPG, ≤6MB)

アドオンプラン（addons）

atoa addons list                        # current plan, feature usage, available moves
atoa addons upgrade                     # pick a plan on a TTY, or pass a plan ID
atoa addons downgrade <planId>          # refused while usage exceeds the target plan
atoa addons cancel-downgrade            # cancel a downgrade that hasn't taken effect

ダウングレードが拒否された場合、対象プランの上限を超えている機能が表示されるため、再試行する前に何を減らせばよいか確認できます。

口座振替（direct-debit）

事業者が保有できる口座振替の委任は1件です。有効化されている場合、setup は2件目を作成せずに拒否します。

atoa direct-debit status                # whether a mandate exists, and its status
atoa direct-debit setup                 # interactive: bank details + billing address

対話型セットアップでは、事業者に登録済みの口座名義人名、メールアドレス、請求先住所があらかじめ入力されます。また、登録済みの口座番号はマスク表示されます。そのまま使う場合は Enter キーを押してください。

通知設定（comms）

atoa comms list                         # topics, with each channel's state
atoa comms set payouts --email off      # topic ID or display name
atoa comms set <topicId> --sms on --push off

各チャネルの状態は on、off、unavailable のいずれかです。Atoa はすべてのトピックで各チャネルを送信するわけではなく、利用できないチャネルを有効にすることはできません。

チェックアウトのブランディングと SMS の送信者名（custom-branding、custom-sms）

atoa custom-branding get                # current checkout theme colour
atoa custom-branding set '#FF0000'      # 6-digit hex
atoa custom-branding reset              # restore the Atoa default

atoa custom-sms list                    # sender name and its review status
atoa custom-sms set AcmeLtd             # request a sender name (3-11 chars; letters, numbers, spaces)
atoa custom-sms delete --yes            # remove the custom sender name

加盟店のオンボーディング（signup）

atoa signup の実行に事前のログインは不要です。アカウント（メールアドレス＋ワンタイムコード）とその JWT セッションを作成してから、オンボーディングウィザードを実行します。

atoa signup                             # interactive: email + OTP, then guided onboarding
atoa signup --email [email protected]     # skip the email prompt
atoa signup --fromStep 2                # resume from step N (2-3); businessId must already be set
atoa signup --deviceName "Work laptop"  # label this device in your Atoa sessions

プロンプトで入力する値にはすべて対応するフラグがあるため、ターミナルなしで signup を実行できます。ワンタイムコードは受信トレイに届くため、2回に分けて実行します。

atoa signup --email [email protected] --output json
#   → exit code 9: "An OTP has been sent to [email protected]."

atoa signup --email [email protected] --otp 123456 --accept-terms \
  --business-name "Acme Ltd" --industry "Retail - Other" \
  --monthly-turnover "Up to £10,000" --business-structure "Limited Company" \
  --vat-number 123456789 --first-name Ada --last-name Lovelace \
  --postal-code "SW1A 2AA" --address-line1 "10 Downing Street" --output json

--accept-terms は、プライバシーポリシーおよび利用規約への同意を記録します。--marketing は別途、オプトインするためのオプションです。--start-new を指定すると、既存の signup を再開するのではなく、2つ目の事業者を作成します。

--business-structure に指定できる値は Limited Company または Charity です。--industry と --monthly-turnover の値は環境によって異なる、サーバー定義のリストです。そのため、上記の値は例にすぎません。オプション名を指定してください。一致する値がない場合、CLI はコード 3 で終了し、選択できる有効な値をすべて表示します。

---

Idempotency-Key — 二重請求の防止

CLI は、POST/PUT/PATCH のたびに新しい Idempotency-Key: <uuidv4> ヘッダーを自動生成します。Atoa サーバーはこのキーを使って再試行を重複排除するため、応答時にネットワークが一時的に途切れても、顧客への二重請求は発生しません。

対話型の利用では、これについて考える必要はありません。そのまま機能します。複数回の CLI 呼び出しにまたがる単一の論理操作（ジョブの再起動など）を扱う CI／スクリプトでの再試行 では、--idempotencyKey を渡してください。再実行時に同じキーが使われ、サーバーが重複を排除します。

# Auto-generated key (default — safe for interactive use)
atoa refunds create --paymentRequestId pr_abc --amount 5.00

# Stable key (CI retry-safe — same key on every re-run of the same run)
atoa refunds create \
  --paymentRequestId pr_abc \
  --amount 5.00 \
  --idempotencyKey "atoa-cli/refund/${RUN_ID}/${PAYMENT_ID}"

atoa payments create、atoa refunds create、atoa card-on-file charge、汎用の atoa post で使用できます。それ以外の POST エンドポイントでは、自動生成されたキーが常に送信されるため、デフォルトで安全に再試行できます。

---

よくあるワークフロー

支払い

atoa payments create --amount 25.00 --orderId order-001 --customerId cust_123 --redirectUrl https://shop.example.com/return
atoa payments status pr_abc123 --poll
atoa payments cancel pr_abc123 --yes
atoa payments transactions --from 2026-01-01 --to 2026-01-31 --status COMPLETED
atoa payments transactions --pageAll --output json   # walk every page

顧客と保存済みカード

atoa customers create --fullName "Jane Doe" --email [email protected] --type INDIVIDUAL
atoa customers list --search jane
atoa customers get cust_123
atoa customers update cust_123 --vatNumber GB123456789
atoa customers delete cust_123 --yes
atoa payment-methods list --customer cust_123
atoa payment-methods get card_456 --customer cust_123
atoa payment-methods delete card_456 --customer cust_123 --yes

カードオンファイル（保存済みカードでの請求）

atoa card-on-file charge --customerId cust_123 --paymentMethodId card_456 --amount 10.50 --orderId order-007
atoa card-on-file charge --customerId cust_123 --paymentMethodId card_456 --amount 10.50 --orderId order-007 --captureType MANUAL_CAPTURE
atoa card-on-file capture pr_abc123 --yes
atoa card-on-file cancel pr_abc123 --yes

返金

atoa refunds create --paymentRequestId pr_abc123 --amount 5.00 --currency GBP --notes "duplicate charge" --yes
atoa refunds list --paymentRequestId pr_abc123
atoa refunds cancel rf_xyz --yes

Webhook

atoa webhooks create --url https://your-app.com/webhooks --event PAYMENTS_STATUS
atoa webhooks create --url https://your-app.com/webhooks --event PAYMENTS_STATUS \
  --authentication @./auth.json                              # OAuth/Basic secret from file (NOT inline — see below)
atoa webhooks list
atoa webhooks delete wh_123 --yes

⚠ 認証シークレットは --authentication @path/to/auth.json（または標準入力の場合は --authentication -）で渡してください。インライン JSON（--authentication '{"clientSecret":"..."}'）も使用できますが、シークレットが ps、シェルの履歴、監査ログに露出します。スクリプトでの使用は避けてください。

Webhook テストのトリガー（サンドボックスのみ）

atoa webhooks trigger は、登録済みのサンドボックス Webhook URL に偽のイベントを送信します。実際の支払いは不要で、本番イベントと同じ本文形式および署名の生成方法が使われます。--env にかかわらず、常にサンドボックスキーを使用します。

対応イベント：PAYMENTS_STATUS、EXPIRED_STATUS、REFUND_STATUS、POS_PAYMENT_STATUS。

# Defaults — fires a PAYMENTS_STATUS event with a generated orderId
atoa webhooks trigger PAYMENTS_STATUS

# Override fields in the dispatched body
atoa webhooks trigger PAYMENTS_STATUS --paymentMethod CARD --status AUTHORIZED
atoa webhooks trigger PAYMENTS_STATUS --orderId order-001 --amount 25.00
atoa webhooks trigger REFUND_STATUS --status FAILED

# POS_PAYMENT_STATUS has multiple body shapes — pick one via --type
atoa webhooks trigger POS_PAYMENT_STATUS --type PAYMENTS_STATUS
atoa webhooks trigger POS_PAYMENT_STATUS --type REFUND_STATUS --status COMPLETED
atoa webhooks trigger POS_PAYMENT_STATUS --type EXPIRED_STATUS
atoa webhooks trigger POS_PAYMENT_STATUS --type PAYMENTS_STATUS \
  --customFields '[{"value":"CUST_001","fieldName":"Customer ID"}]'

フラグ	用途
--orderId	送信する本文の orderId を上書きします
--amount	ポンド単位の paidAmount を上書きします（例：£10.05 の場合は 10.05）
--paymentMethod	CARD | PAY_BY_BANK
--status	COMPLETED | AUTHORIZED | FAILED | CANCELLED | EXPIRED（イベントごとの検証はサーバー側で行われます）
--type	POS_PAYMENT_STATUS のみ — 本文形式：PAYMENTS_STATUS（デフォルト）／REFUND_STATUS／EXPIRED_STATUS
--customFields	POS_PAYMENT_STATUS のみ — {value, fieldName} の JSON 配列

銀行フィード（オープンバンキング）

atoa bank-feed initiate --redirectUrl https://example.com/bank/return
atoa bank-feed accounts auth_999
atoa bank-feed account acct_111
atoa bank-feed balance acct_111
atoa bank-feed transactions acct_111 --from 2026-01-01 --before 2026-02-01
atoa bank-feed revoke --accountAuthId auth_999 --yes

ストア、金融機関、入金

atoa stores list
atoa institutions list
atoa payouts list --fromDate 2026-01-01 --status COMPLETED
atoa payouts transactions po_555 --pageAll

デバイスキー（ローテーション／取り消し）

atoa keys revoke                              # interactive: picks env if profile has both
atoa keys revoke --env sandbox --yes          # non-interactive
atoa keys revoke <sdkAccessId> --yes          # revoke a specific key by id
atoa keys regenerate                          # rotate active env's key — new bearer shown ONCE
atoa keys regenerate --env production --yes

汎用 HTTP メソッド（柔軟な対応）

CLI がまだラップしていないエンドポイントを使う場合や、明示的に制御したい場合に使用します。これらの認証には SDK キー が使われるため、先に atoa keys create を実行しておく必要があります。

atoa get /api/payments/stores
atoa get /api/customers -d page=0 -d size=20 --pageAll
atoa post /api/something --data @body.json
atoa post /api/something --data @body.json --idempotencyKey "ci-${RUN_ID}"
atoa delete /api/customers/cust_123 --yes

---

よく使うフラグ

リソースコマンド（payments、refunds、customers など）

すべてのリソースコマンドで、同じ6つのグローバルフラグを使用できます。リソースの各トピック（payments、refunds、customers、payment-methods、card-on-file、webhooks、bank-feed、payouts、stores、institutions、keys、whoami、get／post／delete）の任意の末端コマンドで使用してください。

フラグ	用途
--env	このコマンドに限り環境（sandbox | production）を上書きします
--output	json | table | yaml（デフォルト：json）
--verbose	メソッド、URL、伏字にした Authorization を標準エラーに出力します
--dryRun	リクエストを解決し、送信せずに表示します
--yes	確認プロンプトをスキップします（CI で破壊的なコマンドを実行する場合は必須です）
--profile	特定のプロファイルを対象に操作します（activeProfile を上書きします）

管理コマンド（login、logout、reset、profile/*）

これらのコマンドはリソースコマンドのグローバルフラグを受け付けず、用途に特化した独自の引数セットがあります。よく使うものは次のとおりです。

コマンド	主なフラグ
atoa login	--profile
atoa logout	--env、--profile、--revoke、--yes、--dryRun
atoa reset	--revoke、--yes、--dryRun
atoa profile set	--profile、--yes、--dryRun（および key=value の位置引数）
atoa profile delete	--yes、--dryRun
atoa profile use	--dryRun
atoa profile rename	--yes、--dryRun

コマンドごとのフラグ一覧は、atoa <command> --help を実行して確認してください。

---

出力形式

atoa payments transactions --output json   # default — JSON to stdout
atoa profile list --output table           # human-readable
atoa whoami --output yaml

stdout が TTY かどうかにかかわらず、デフォルトは JSON です。そのため、明示的に --output json を指定しなくても、常に jq にパイプできます。

---

シェル補完

この CLI には、コマンド名、フラグ名、動的な値（ライブのプロファイル名、sdkAccessIds、--env の値）を補完する TAB 補完機能があります。各シェルでのインストールは 1 回だけです。

atoa completion <bash|zsh|pwsh>

シェル	1 行でのインストール
bash	atoa completion bash >> ~/.bashrc && source ~/.bashrc
zsh	atoa completion zsh > ~/.zsh/completions/_atoa（compinit より前に、そのディレクトリが fpath に含まれていることを確認してください）
PowerShell	atoa completion pwsh | Out-String | Invoke-Expression（永続化するには $PROFILE に追記してください）

インストール後、<TAB> を押します。

atoa <TAB>                       → login, keys, profile, payments, …
atoa keys revoke <TAB>           → your live sdkAccessIds
atoa profile use <TAB>           → your live profile names
atoa --env <TAB>                 → sandbox, production

TAB でファイル補完に切り替わりますか？ ラッパーが読み込まれていません。まずエンジンを確認してください。

atoa --complete-bash "atoa profile use "

候補が表示された場合、エンジンは正常に動作しています。新しいターミナルでインストールを再実行してください。

---

設定／環境変数

変数	用途
ATOA_HOME	設定と認証情報の保存場所を上書きします。デフォルトは $HOME です。認証情報は $ATOA_HOME/.atoa/auth/ に保存されます。Docker、サンドボックス化された CI、一時的なコンテナーで便利です。
ATOA_PROFILE	デフォルトのプロファイル名です。すべてのコマンドで --profile <name> を渡すのと同じです。明示的なフラグが優先されます。長時間実行するスクリプトで export ATOA_PROFILE=ci && atoa … のように指定すると便利です。
ATOA_BASE_URL	変更されていません。実行時に Atoa 決済 API のベース URL を上書きします。
ATOA_DASHBOARD_URL	ブラウザーログイン許可ページで使用するダッシュボード URL を上書きします（ビルド定義のデフォルト値：https://dashboard.paywithatoa.co.uk）。ビルド時に DASHBOARD_URL tsup 定義で、または実行時にこの変数で設定します。セルフホストまたはステージングのダッシュボードをデプロイする場合に便利です。

---

終了コード

この CLI は POSIX 形式の終了コードを使用するため、シェルパイプラインや CI システムで失敗の種類に応じた分岐ができます。

コード	意味	発生条件
0	成功	コマンドがエラーなしで完了しました
1	一般的な失敗	以下に分類されないすべてのケース
2	認証／アクセス拒否	HTTP 401 または 403 — トークンが無効、失効、または権限がありません
3	検証エラー	HTTP 400、またはクライアント側で入力が拒否された場合（不正な金額、不正な JSON、不正な列挙値）
4	見つかりません	HTTP 404 — この環境にリソースが存在しません
5	レート制限	HTTP 429、またはワンタイムコード／サインインのスロットリング — 処理を停止して待機してください。再試行するとブロック期間が延長されます
6	ネットワーク／TLS／DNS	サーバーに接続できませんでした（接続拒否、DNS、証明書の期限切れ、タイムアウト）
7	ビジネスが選択されていません	アカウントが複数のビジネスに属しており、どれもアクティブではありません — atoa business use <id> を実行してください
8	プランの上限	アドオンプランでは許可されていません — atoa addons list で上限を確認できます
9	ワンタイムコードを送信しました	失敗ではありません。コードが送信され、何も書き込まれていません。同じコマンドを --otp <code> を付けて再実行してください

CI のパターン例：

if ! atoa refunds create --paymentRequestId "$PR" --amount 5.00 --idempotencyKey "$RUN_ID" --yes ; then
  case $? in
    2) echo "Token invalid — re-login required" ;;
    3) echo "Bad input — fix the payload" ;;
    5) echo "Throttled — wait it out; retrying extends the block" ;;
    6) echo "Network blip — retry the same idempotency key is safe" ;;
    *) echo "Unhandled error" ;;
  esac
  exit 1
fi

---

CI／自動化

atoa login では対話型ブラウザーが必要なため、CI ランナー自身ではログインできません。ワークステーションで認証情報を準備し（atoa login、ジョブで SDK／データ関連のコマンドを実行する場合は atoa keys create も実行）、~/.atoa/auth/ のファイルをランナーから利用できるようにします。ファイルを格納したディレクトリを ATOA_HOME に指定してください。

# 1. With credentials already provisioned (ATOA_HOME → the auth dir),
#    target the CI profile with a stable idempotency key
atoa --profile ci payments create \
  --amount 10.00 --orderId "$RUN_ID" --customerId cust_123 --redirectUrl https://x \
  --idempotencyKey "ci-payment/$RUN_ID" --dryRun

# 2. Read-only checks
atoa --profile ci payments transactions --output json --status COMPLETED

# 3. Clean up (revokes the server-side key too; safe to share across machines)
atoa logout --profile ci --revoke --yes

主なパターン：

• --profile ci は、すべてのコマンドを名前付きの認証情報セットに限定します。ATOA_PROFILE=ci と同じ形式のフラグです。
• --idempotencyKey "ci-…/$RUN_ID" を指定すると、同じ CI ジョブを再実行しても、決済／返金／請求が重複して作成されません。
• --dryRun を使うと、実行前に CI ステップで解決済みのリクエスト本文を検証できます。
• --yes は確認プロンプトをスキップします。TTY のない環境では、破壊的なコマンドごとに必須です。

---

トラブルシューティング

ログイン後に HTTP 401 が発生する

セッションの有効期限が切れたか、取り消された可能性があります（例：同じデバイスで後からログインしたことで、以前のセッションが無効になった場合）。atoa whoami を実行してアクティブなプロファイルを確認し、atoa login を再実行してセッションを更新してください。

No profile is configured. Run \atoa login` to pair this device.`

初回実行時の状態です。ペアリングするには、atoa login を実行してください。

Multiple profiles are configured (a, b, c). Run \atoa profile use ` …`

ペアリング済みの加盟店が複数あり、デフォルトが設定されていません。atoa profile use <name> を一度実行するか、各コマンドに --profile <name> を指定してください。

Timed out acquiring lock on …/session.json.lock

別の atoa プロセスが書き込み中です。他のプロセスが実行されていない（たとえば、プロセスがクラッシュした）場合は、ロックファイルを手動で削除してください。

rm ~/.atoa/auth/session.json.lock

Refusing to read …/session.json: insecure permissions（POSIX のみ）

セッションファイルにグループまたはその他のユーザーの読み取り権限が設定されています。次のように修正してください。

chmod 600 ~/.atoa/auth/session.json

Refusing to parse …/session.json: not valid JSON

ファイルが破損しています。次のように復元してください。

atoa reset --yes && atoa login

---

ドキュメント

• ドキュメント全文： Atoa Docs
• 組み込みヘルプ： atoa --help、atoa <command> --help、atoa <command> <subcommand> --help — コマンドごとのフラグ一覧を確認できます。インストール済みのバイナリと常に同期されています。
• API リファレンス： Atoa ダッシュボードにあるドキュメントサイトへのリンクをご覧ください。

---

リセット／アンインストール

atoa reset --yes                     # wipe local profiles + tokens (local only)
atoa reset --revoke --yes            # also revoke server-side keys (best-effort)
atoa reset --dryRun                  # preview what would be cleared without touching state
npm uninstall -g @atoapayments/atoa-cli   # remove the binary

---

サポート

[email protected] までお問い合わせいただくか、ダッシュボードのチャットをご利用ください。