npm package: @mercuryo-ai/magicpay-cli
Description: Protected-form CLI for prepared browser pages
Latest version: 0.1.7

# @mercuryo-ai/magicpay-cli

[![npm version](https://img.shields.io/npm/v/@mercuryo-ai/magicpay-cli)](https://www.npmjs.com/package/@mercuryo-ai/magicpay-cli) [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)

Safely fill logins, identity forms, and payment details from stored secrets —
without exposing them to the agent.

MagicPay CLI handles the sensitive part of a browser workflow: when the page
is already at a login, identity verification, or payment form, MagicPay
discovers the form, requests human approval for the right stored credentials,
and fills them through a guarded path. The agent never sees the actual values.

Navigate to the target page first with a browsing tool (like AgentBrowse) or
an existing browser session, then hand the form over to MagicPay.

## Install

```bash
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`.

```bash
magicpay init <magicpay-api-key>
magicpay status
```

`magicpay status` is the normal readiness check before a protected-form task.
Use `magicpay doctor` only when `init` or `status` still fail and you need to
inspect the local config.

## Core Flow

1. `magicpay attach <cdp-url>`
2. `magicpay start-session [name]`
3. `magicpay find-form`
4. `magicpay get-secrets-catalog` only if candidates are missing or stale
5. `magicpay request-secret <fillRef> <storedSecretRef> --merchant-name <name>`
6. `magicpay poll-secret <requestId>`
7. `magicpay fill-secret <fillRef> <requestId>`
8. `magicpay submit-form <fillRef>` only if the guarded fill flow explicitly
   leaves submission unfinished
9. `magicpay end-session` when the protected step is complete

Example:

```bash
magicpay attach <cdp-url>
magicpay start-session "Checkout"
magicpay find-form
magicpay request-secret <fillRef> <storedSecretRef> --merchant-name "Example Store"
magicpay poll-secret <requestId>
magicpay fill-secret <fillRef> <requestId>
```

If `find-form` does not return the right candidates, refresh the catalog and
retry:

```bash
magicpay get-secrets-catalog
magicpay find-form
```

## Operating Rules

- Start from a prepared page, not from generic browser navigation.
- Use `magicpay status` before a new protected-form task.
- Re-run `magicpay find-form` after meaningful page changes.
- Treat `magicpay submit-form` as manual recovery, not as the default happy
  path.
- `mock-approve-secret` and `mock-deny-secret` are development-only helpers,
  not production approval flows.

## Command Groups

- Setup and diagnostics: `init`, `status`, `doctor`
- Session control: `attach`, `start-session`, `end-session`
- Protected form flow: `find-form`, `get-secrets-catalog`, `request-secret`,
  `poll-secret`, `fill-secret`, `submit-form`
- Development-only helpers: `mock-approve-secret`, `mock-deny-secret`

## Companion Tools

- You only need browser navigation, observation, or extraction:
  use `@mercuryo-ai/agentbrowse-cli`
- You want one CLI for both browser work and protected fills:
  use `@mercuryo-ai/magicpay-agent-cli`