@mercuryo-ai/magicpay-cli

Safely fill login, identity, checkout, donation, subscription, and payment pages from MagicPay Memory.

MagicPay CLI handles the Memory fill part of a browser session. It uses the active MagicBrowse browser session to observe visible field targets, fetches value-free Memory item descriptors from MagicPay, lets the Memory matcher choose semantic matches, plans the fill by fieldRef, and applies the plan without exposing raw values to the agent driving it.

The current product fill path is Memory target matching plus plan-fill / apply-fill.

Use it together with any browser-automation tool (for example @mercuryo-ai/magicbrowse-cli) that opens the page and attaches to the browser over the Chrome DevTools Protocol (CDP).

Mental Model

These terms appear throughout this README:

• <cdp-url> — WebSocket URL of an already running Chrome session, produced by whatever tool opened the browser.
• Memory item descriptor — a value-free field description from MagicPay Memory. It contains refs and safe semantic facts, not raw values.
• fieldRef — the opaque Memory field reference chosen by the matcher. The planner uses it as the canonical key for the fill; field labels and field types are metadata, not deterministic match keys.
• plan-fill — observes the current browser page, fetches value-free Memory descriptors, runs the Memory matcher, builds a value-free fill plan, and stores the latest short-lived plan in the active workflow.
• payment_card.authorization_required — a plan-fill blocker/warning that means MagicPay Memory has a provider-backed payment card, but card handles are hidden until payment authorization is approved for the active workflow session.
• apply-fill — refreshes the browser snapshot, materializes only the approved values needed for the active plan, writes them into the browser through MagicBrowse, and stops before final commitment actions such as Pay, Book, Send, or Submit.
• currentRequestId — the pending runtime request saved by a typed action command with --return-pending, then reused by confirm-otp and wait-request.
• protected values — secrets the user must approve each time (passwords, card numbers, identity documents). Released only through Memory value materialization after the fill plan is approved or through a typed action command on a live MagicPay workflow.

Install

npm i -g @mercuryo-ai/magicpay-cli@latest

API Setup

Configure the API key once:

Get an account and API key at https://agents.mercuryo.io/signup.

magicpay init <magicpay-api-key>
magicpay status

The CLI uses its bundled default MagicPay gateway URL for normal setup. No URL parameter is needed unless you intentionally target another environment.

magicpay status is the normal readiness check before a secure form fill. Use magicpay doctor when init or status still fail and you want to inspect the local config.

To point the CLI at a non-default MagicPay environment (staging, self-host, test), pass --api-url to init:

magicpay init <magicpay-api-key> --api-url https://your-magicpay-endpoint/functions/v1/api

The URL is persisted into the active MagicPay home config alongside the key: ~/.magicpay/config.json by default, or $MAGICPAY_HOME/config.json when MAGICPAY_HOME is set.

Workflow

1. magicpay status
2. magicpay start-session [name]
3. magicpay launch [url] or magicpay attach <cdp-url> when a browser child is needed inside the active product workflow
4. magicpay solve-captcha [--timeout <s>] only when a real CAPTCHA is confirmed on the current page
5. Run magicpay plan-fill for the current page. The command observes the browser, loads value-free Memory descriptors, runs the matcher, and stores the latest plan. If the result includes payment_card.authorization_required, the Memory store has a provider-backed payment card but MagicPay cannot reveal card handles until authorize-payment is approved in this session.
6. Run magicpay apply-fill. The command refreshes the browser snapshot, materializes Memory handles inside MagicPay, fills through MagicBrowse primitives, and stops before final commitments. If it returns memory.choose_candidate, ask the user which displayed Memory candidate to use, then run magicpay choose-memory --choice <choiceId>.
7. For protected actions, use the typed command that matches the action: magicpay authorize-payment ..., magicpay sign-message ..., or magicpay confirm-action ...
8. For non-blocking approval handoff, add --return-pending to the typed action command, then either let the user approve in MagicPay web/mobile or run magicpay confirm-otp --otp <digits> after the user provides the OTP. In both cases, finish with magicpay wait-request.
9. Continue the browser task with the browser owner. Final commitment buttons are separate orchestrator decisions, not part of Memory field fill.
10. magicpay end-session when the product workflow is complete

Flag details:

• --timeout <s> sets how long solve-captcha waits for confirmed challenges on the current browser child.
• --planner-hint <text> passes a short human-readable hint about the current form to plan-fill. It must not contain page targets, targetMatches, Memory catalogs, materializers, browser writers, or raw Memory values.
• apply-fill --plan <planId> applies a specific stored fill plan instead of the latest active plan.
• choose-memory --choice <choiceId> submits a backend-owned Memory candidate choice id returned by apply-fill, then continues applying the fill plan.
• --return-pending makes a typed action command return after creating the pending request instead of blocking for the result.
• confirm-otp --otp <digits> confirms the active pending request by OTP. --session <id> and --request <id> can recover an explicit request.
• wait-request resumes waiting for the active pending request. It also accepts --session <id> and --request <id>.
• list-memory-items, get-memory-item, delete-memory-item, create-memory-item, add-memory-field, update-memory-field, and delete-memory-field are UX-first wrappers over the SDK Memory item APIs. Raw item JSON is available only through --raw-item-json for service/debug use.

Example:

magicpay start-session "Checkout"
magicpay attach <cdp-url>
magicpay plan-fill
magicpay apply-fill

The workflow is:

• plan-fill observes page targets and runs the Memory matcher over value-free descriptors;
• plan-fill returns a handles-only fill plan;
• if a provider-backed card exists but needs payment authorization, plan-fill returns the non-blocking blocker payment_card.authorization_required and a diagnostic warning instead of card handles;
• apply-fill fresh-observes, materializes approved values and writes only the planned fields through MagicBrowse, then stops;
• the browser owner continues from the filled state;
• typed action approvals cover the matching final action. After successful authorize-payment, do not ask again before the approved payment submit unless amount, currency, recipient, or recurring facts changed.

Typed Action Commands

Use typed action commands when the next browser or wallet step is consequential and needs MagicPay approval:

• magicpay authorize-payment --amount <number> --currency <code> --recipient <name> [--description <text>] [--recurring <true|false>] [--authorization-ref <ref>] [--item-ref <itemRef>] [--return-pending] approves one payment. Collect the final visible amount, currency, merchant/payee recipient, optional description, and optional recurring status first. After approval, proceed with the matching payment form fill and final Pay/Submit action. Stop and ask again only if amount, currency, recipient, or recurring status changed. If plan-fill previously returned payment_card.authorization_required, rerun plan-fill after approval so the active session can receive the provider-backed card handles.
• magicpay sign-message --item-ref <walletItemId> --message <text> [--return-pending] approves signing that exact wallet message with the selected wallet item. Stop and ask again if the message changes.
• magicpay confirm-action --summary <text> [--details <text>] [--return-pending] approves a non-payment consequential action that has no more specific typed command. Use a short visible summary, and add details when the page context or consequences need to be explicit.

Typed approvals are exact. They do not authorize changed facts, broader future actions, or unrelated page steps.

Memory Item Commands

Use Memory item commands when the runtime needs to manage saved reusable Memory records directly. These commands return JSON on stdout like the rest of the CLI.

A Memory item is a user-owned reusable data record, not a single field. The item label names the record that future agents and users will recognize, while fields hold the reusable facts inside that record. Choose short labels that describe the purpose of the group, such as Airline login, Traveler profile, Home shipping address, Wallet, or Facts about user. Do not include raw values in labels, do not use one field label as the item label when the item contains a broader record, and do not create one item per field unless the user is saving one truly standalone fact.

magicpay list-memory-items --url https://airline.example/login --status active
magicpay list-memory-items --all-sites
magicpay get-memory-item --item-id mem_airline_login
magicpay delete-memory-item --item-id mem_airline_login
magicpay create-memory-item \
  --item-label "Airline login" \
  --site airline.example \
  --text "Login [email protected]" \
  --secret-text "Password=correct-horse"
magicpay create-memory-item \
  --item-label "Traveler profile" \
  --person "Full name=Ada Lovelace" \
  --date "Date of birth=1815-12-10" \
  --phone "Phone=+14155550100" \
  --secret-phone "Backup phone=+14155550101"
magicpay add-memory-field \
  --item-id mem_airline_login \
  --label "Recovery code" \
  --value "123456" \
  --secret true \
  --hint "One-time recovery code"
magicpay update-memory-field \
  --field-ref field_login_email \
  --value [email protected]
magicpay update-memory-field \
  --field-ref field_phone \
  --type text
magicpay update-memory-field \
  --field-ref field_password \
  --label "Account password" \
  --secret true \
  --hint "Account password"
magicpay delete-memory-field --field-ref field_recovery_code

list-memory-items and get-memory-item return item ids, labels, statuses, read-only markers, and field refs with labels/hints, never raw values. Provider-backed cards can appear as readOnly: true; they are available for fill but cannot be updated through Memory CRUD. Use --url <current-url> for ordinary site-scoped lookup; use --all-sites only for explicit global Memory review or editing.

On create, fields are new, so --text, --date, --phone, --person, and their --secret-* variants use "Label=value". Existing fields are never addressed by label. List or get the item first, select the intended fieldRef, then use update-memory-field --field-ref <fieldRef> or delete-memory-field --field-ref <fieldRef>.

add-memory-field and update-memory-field accept --type text|date|phone_number|person_name. text clears semantic value type. Use date with canonical YYYY-MM-DD, phone_number with E.164 such as +14155550100, and person_name with a non-empty full name string. Internal card value types such as payment_card_number and payment_card_expiry are provider-backed only and are rejected by public Memory item commands.

--secret true|false is mutable display/logging metadata for any field. It is not a value type and is not an encryption mode.

For chat-provided reusable facts, the expected flow is: list Memory items, find a suitable editable item by label, scope, fields, and hints, then update fields by fieldRef. Create a new item only when no semantically suitable item exists. Use Facts about user only for global profile facts with no narrower record; use a narrower label for site/account-specific logins, traveler profiles, addresses, wallets, payment-related records, and other coherent groups. Field labels should be short human text. Hints should help a future agent understand when to use a field, for example Login email or username or Passport expiry date in YYYY-MM-DD; do not put raw values or generic text like value in hints.

create-memory-item --raw-item-json and update-memory-item --raw-item-json exist only as service/debug escape hatches for lower-level SDK payloads. Do not teach them as the main Memory UX.

Pending Approval And OTP

OTP is optional. A pending approval request can be completed in MagicPay web, MagicPay mobile, or by OTP when the request is eligible and the user chooses to provide the OTP they received.

magicpay confirm-action --summary "Send the prepared support message" --return-pending
# User approves in MagicPay UI, or provides the OTP they received:
magicpay confirm-otp --otp <digits>
magicpay wait-request

If the user approves in MagicPay UI, skip confirm-otp and still run magicpay wait-request. Do not ask for OTP before a typed action command with --return-pending returns a pending request, and do not log, store, or repeat the OTP in summaries.

Session Lifecycle

A MagicPay task uses one workflow session that covers everything between start-session and end-session. Three things to know:

• State lives on disk in ~/.magicpay/workflow-state.json by default, or $MAGICPAY_HOME/workflow-state.json when MAGICPAY_HOME is set. Commands read and update this file, so you can run them as separate processes. Only one workflow runs at a time per MagicPay home. Use a distinct MAGICPAY_HOME for isolated live tests or parallel workflows. For the full layout of the MagicPay home, see @mercuryo-ai/magicpay-home.
• Always finish with end-session. It marks the session complete on the server. If you forget, the session is eventually cleaned up by its server-side TTL. A later start-session now attempts to cancel or clear the previous workflow binding before creating a new one, but manual recovery can still be needed if the remote state cannot be finalized.
• Recovery. If a CLI process is killed mid-flow, the state file is still there. Start with magicpay status, then use magicpay end-session or a fresh start-session, followed by launch or attach on the approved browser when browser-dependent work resumes. Re-observe the page and rebuild Memory target matches after any meaningful page change; do not reuse a fill plan from a stale page fingerprint.

A session can end without an artifact when the user denies, the request expires, or the session is stopped server-side. Those cases surface as { success: false, reason: 'denied' | 'expired' | 'canceled' | ... } — see the JSON Output And Exit Codes section.

JSON Output And Exit Codes

Every command returns a single JSON object on stdout and exits with a status code:

• Success: JSON includes { "success": true, ... }, exit code 0.
• Failure: JSON includes { "success": false, "error": "<message>", ... }, exit code 1.
• Fatal error before the command could run: a single line written to stderr in the form [magicpay] Fatal: <message>, exit code 1.

Example failure after an approval was denied:

{
  "success": false,
  "action": "apply-fill",
  "error": "REQUEST_DENIED",
  "reason": "denied",
  "message": "The user denied this request."
}

Check success first, then outcomeType, then branch on reason (for request-level failures such as denied, expired, failed, canceled, timeout) or on the command-specific error code. plan-fill may also return non-fatal blockers and diagnostics.warnings. For provider-backed cards, branch on kind: "payment_card.authorization_required" and status: "authorization_required"; the warning text is for display only.

Operating Rules

• Use magicpay status before a new MagicPay task, then start the product workflow with magicpay start-session.
• Use magicpay launch or magicpay attach only after start-session, when MagicPay needs a browser child inside the active product workflow. Re-attaching the same endpoint is allowed but is not required as a ritual.
• Re-observe the page and rebuild the Memory fill plan after meaningful page changes.
• Treat post-fill browser continuation as browser-owner work. MagicPay does not click final commitment controls as part of field fill.
• Treat payment_card.authorization_required as a card-present state, not as a prompt to collect raw card values. Use authorize-payment when the current payment needs that card, then re-plan.
• Before a consequential action, get the matching typed MagicPay approval: authorize-payment, sign-message, or confirm-action.
• After typed approval, proceed with exactly that action; stop only if page facts changed.
• Treat approval as channel-neutral: MagicPay UI and OTP resolve the same pending request. OTP is never mandatory.
• Do not print, log, summarize, or persist OTP values.
• Development-only approval mocks are not production approval flows.

Command Groups

• Setup and diagnostics: init, status, doctor
• Session control: start-session, launch/attach, end-session
• CAPTCHA recovery: solve-captcha
• Memory fill: plan-fill, apply-fill
• Memory items: list-memory-items, get-memory-item, delete-memory-item, create-memory-item, add-memory-field, update-memory-field, delete-memory-field
• Secure actions: authorize-payment, sign-message, confirm-action, confirm-otp, wait-request

Companion Tools

• You only need browser launch, attach, observe, or act: use @mercuryo-ai/magicbrowse-cli
• You need browser work and protected fills in one flow: use @mercuryo-ai/magicbrowse-cli for browser control and @mercuryo-ai/magicpay-cli for sensitive steps.