paypal-cli

name

paypal-cli

description

Use this skill for service operations only. DO NOT use this skill for CLI implementation lifecycle work such as creating, testing, updating, troubleshooting, validating, removing, or documenting the CLI tool itself; delegate those tasks to cli-tool-expert. Execute paypal operations using the `paypal` CLI tool. CLI interface for PayPal API. Triggers: paypal, paypal cli, paypal payouts, send paypal payment, paypal batch payout, pay someone with paypal, paypal payout status, my paypal, paypal auth profiles

Execute paypal operations using the `paypal` CLI. All paypal interactions should use this CLI.

<quick_start> The paypal CLI follows this pattern:

paypal <command-group> <action> [arguments] [options]

Task	Command
Check auth status	paypal auth status
Send a payout	paypal payouts create --receiver [e-mail] --amount 10.00
Check batch status	paypal payouts get BATCH_ID
Get payout item	paypal payouts get-item ITEM_ID
Cancel unclaimed payout	paypal payouts cancel-item ITEM_ID
Preview a direct capture refund	paypal refunds create CAPTURE_ID --amount 4.50 --dry-run
Preview a BrickLink refund	paypal refunds from-bricklink ORDER_ID --amount 4.50 --dry-run
Preview with verified BrickLink order JSON	paypal refunds from-bricklink ORDER_ID --order-json order-context.json --amount 4.50 --dry-run
Refresh browser session	paypal auth login -c browser_session --force
List profiles	paypal auth profiles list --table
Switch profile	paypal auth profiles set-default production

Auth status output uses the shared profile shape: {"profiles":[{"name":"default","authenticated":true,"credential_types":{...}}]}. Read auth profiles[].authenticated for per-profile status; do not expect a flat top-level authenticated field. </quick_start>

<essential_principles> MANDATORY: Consult the adjacent usage.json at <cli-tools-root>/_repo/skills/<tool>-cli/usage.json before executing ANY paypal command. This file contains complete command syntax, all arguments, all options, and usage instructions for every command. Never guess at command syntax.

- **payouts** -- Manage batch payouts (list, create, get, get-item, cancel-item) - **refunds** -- Issue full or partial direct capture refunds through the PayPal API, or BrickLink-assisted refunds through the PayPal unified transactions browser session - **transactions** -- Search PayPal transaction-reporting records - **auth** -- Authentication commands and nested `auth profiles` management When PayPal browser auth is missing, expired, CAPTCHA-blocked, or needed for unified transactions/refunds, follow the shared browser-session auth rule: use Computer Use to open a visible terminal and run `bash -lc 'paypal auth login -c browser_session --force'`. Let the CLI open its normal Chrome login window and complete the login through that flow; retrieve credentials and MFA through the approved CLI-tools paths before asking Adam.

If Computer Use or local GUI control is unavailable under the current host policy, stop and report that blocker. Do not script PayPal credential entry, CAPTCHA navigation, or browser-session capture with Playwright, browser-harness, manual session-file edits, or custom Chrome automation outside this auth command.

PayPal refunds must use `paypal refunds create` for known capture IDs or `paypal refunds from-bricklink` for BrickLink orders. Start with `--dry-run`, verify the printed request, then use `--yes` only when the refund is explicitly approved. `from-bricklink` reads `bricklink order get` by default; use `--order-json` when a customer-service workflow already has verified BrickLink order JSON or when the live BrickLink lookup is blocked. It searches PayPal unified transactions from the saved browser session, verifies buyer email/name/date/amount/refundability, and posts the refund payload through the authenticated PayPal page. Do not use PayPal's web refund sheet manually or `playwright-cli fill` on the refund amount input. PayPal's masked currency field can preserve or transform existing digits even when automation reports a successful fill; that can produce an incorrect amount before the final submit button is clicked.

<reference_index> usage.json -- Complete command tree with arguments, options, defaults, and usage instructions for every command. </reference_index>

<success_criteria>

• Command executes without error
• Output is displayed in requested format
• Correct command and flags used (verified against usage.json) </success_criteria>