AtoA

Atoa CLI

适用于 Atoa 支付 API 的官方命令行界面。可在终端中管理商户、支付、退款、webhook、银行流水和付款；支持脚本化，安全可靠，并且在 sandbox 和 production 环境中保持一致。

文档： Atoa 文档

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

凭据以权限仅限所有者访问（0600）的 JSON 文件形式存储在 ~/.atoa/auth/ 下：JWT 会话保存在 session.json 中，SDK API 密钥保存在 secret_key.json 中。凭据采用普通文件存储（不使用操作系统钥匙串，与 AWS/gcloud/Stripe CLI 一样），因此同一台机器上的自动化程序和编码 Agent 都可以读取。凭据绝不会写入 .env 文件或 shell 历史记录。

---

配置文件与环境

一台机器可以保存多个商户（配置文件）以及两种环境（sandbox 和 production）的凭据。CLI 会将它们彼此隔离，避免在测试会话中意外使用生产密钥。注意：每个二进制文件只连接一个服务器，因此凭据是否可用仍取决于你安装的构建版本（见上文）。

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）不受环境限制——每个配置文件的一个 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 参数和一个随机状态值，然后在随机端口启动一个临时的 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 只会显示一次——请立即保存。需要具备企业管理员角色。

---

双凭据模型

CLI 支持每个配置文件和环境使用两种相互独立的凭据：

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 添加。

凭据以权限仅限所有者访问（0600）的 JSON 文件形式存储在 ~/.atoa/auth/ 下：

文件	内容	索引依据
session.json	JWT 访问令牌和刷新令牌（浏览器登录）	仅按配置文件索引——不受环境限制，因为浏览器登录会连接到一个身份验证后端
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

如果活动配置文件只有 SDK 密钥而没有 JWT 会话，要求 JWT 的命令会显示清晰的错误信息。运行 atoa login（浏览器）以获取 JWT 会话；需要使用 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，可通过 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 的单位是 GBP（例如 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（direct-debit）

每个企业只能有一条授权。授权生效后，setup 会拒绝创建第二条授权。

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 可以在完全没有终端交互的情况下运行。一次性验证码会发送到你的收件箱，所以需要分两次运行：

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 会创建第二个企业，而不是继续现有的注册流程。

--business-structure 的值为 Limited Company 或 Charity。--industry 和 --monthly-turnover 使用的列表由服务器定义，且因环境而异，因此以上值仅供参考——传入相应选项的名称；如果名称不匹配，CLI 会以代码 3 退出，并列出所有可选的有效值。

---

Idempotency-Key — 防止重复扣款

CLI 会在每次 POST/PUT/PATCH 请求中自动生成一个新的 Idempotency-Key: <uuidv4> 标头。Atoa 服务会使用它对重试请求去重，因此即使响应过程中出现网络中断，也不会导致向客户重复扣款。

交互式使用时无需考虑此问题，它会自动生效。对于 CI / 脚本重试，如果一次逻辑操作会跨越多次 CLI 调用（例如作业重启），请传入 --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

Card-on-file（使用已保存的卡扣款）

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、Shell 历史记录和审计日志中暴露密钥——请避免在脚本中使用。

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 数组

银行交易数据（Open Banking）

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 等）

所有资源命令都接受相同的六个全局标志。可在资源主题（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

无论标准输出是否为 TTY，默认格式都是 JSON，因此通过管道传给 jq 时始终可用，无需显式指定 --output json。

---

Shell 补全

CLI 支持对命令名称、标志名称和动态值（实时配置文件名称、sdkAccessIds、--env 值）进行 TAB 补全。每个 Shell 只需安装一次：

atoa completion <bash|zsh|pwsh>

Shell	单行安装命令
bash	atoa completion bash >> ~/.bashrc && source ~/.bashrc
zsh	atoa completion zsh > ~/.zsh/completions/_atoa（确保 fpath 在 compinit 之前包含该目录）
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 风格的退出代码，以便 Shell 管道和 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 Runner 无法自行登录。请在工作站上配置凭据（运行 atoa login；如果作业会执行 SDK／数据命令，还需运行 atoa keys create），然后让 Runner 使用 ~/.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 only)

会话文件设置了组/其他用户可读权限位。请修复：

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 Dashboard 中的文档站点链接。

---

重置 / 卸载

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]，或使用 Dashboard 中的聊天功能。