# CLI reference (/en/cli)



For an assistant to implement payments, copy the prompt in [Connect with AI](/en/agent-kit). MCP host configuration belongs in [Agent connections](/en/agent-kit/connections). This page covers terminal commands; direct HTTP integration is documented in the [API guide](/en/api).

Run the CLI [#run-the-cli]

The official [`@yolfi/agent`](https://www.npmjs.com/package/@yolfi/agent) package requires Node.js 18 or later. Run it without a global installation:

```bash
npx -y @yolfi/agent help
```

Inspect `help` for the commands supported by your installed package version. Payment-management commands return JSON. Check both the command exit status and the response `success` field before continuing. If a command is unavailable, use a supported operation or update the package before relying on it.

Browser authentication [#browser-authentication]

```bash
npx -y @yolfi/agent setup --agent local-agent
```

Open the returned `loginUrl` and complete sign-in and approval. Then run:

```bash
npx -y @yolfi/agent checkin --agent local-agent
npx -y @yolfi/agent auth:status
npx -y @yolfi/agent paylinks:list --page 1 --rows 10
```

The CLI stores a dedicated agent credential in `~/.yolfi/config.json` with owner-only permissions. Check-in must run in the same environment and profile as setup. If it reports `pending`, finish browser approval and retry check-in; if it expires, start a new setup request. See [recovery](/en/agent-kit/connections#verification-and-recovery).

New account signup [#new-account-signup]

Use browser authentication for an existing account. For an explicitly requested new account, after the owner has confirmed their email and project name:

```bash
npx -y @yolfi/agent auth:agent-register \
  --email "owner@example.com" \
  --project-name "Space Shop" \
  --agent-name "local-agent" \
  --integration-intent accept_payments
```

After the owner opens the confirmation email, repeat the same command with the same arguments to finish local check-in. Existing email addresses are rejected by signup; connect them through browser authentication instead. The command stores credentials without printing them.

Non-interactive authentication [#non-interactive-authentication]

For CI or another environment without browser authorization, inject `YOLFI_API_KEY` from your secret manager, then run:

```bash
npx -y @yolfi/agent auth:status
```

Obtain the organization API key through [API key settings](https://app.yolfi.com/settings/api-keys) when no suitable credential already exists. Do not rotate a working key just to connect another agent. Do not paste credentials into chat, commit them, or put them in command examples that will be logged.

Command reference [#command-reference]

Read existing resources before creating or updating them. Commands below are examples to run for the intended operation, not a script to execute from top to bottom.

| Operation                                 | Command                                                                                          |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Inspect authentication and organization   | `auth:status`                                                                                    |
| Read the full organization settings       | `organization:get`                                                                               |
| Update organization details               | `organization:update --json organization.json`                                                   |
| Update only specified settlement networks | `settlement:configure --json settlement.json`                                                    |
| List Paylinks                             | `paylinks:list --page 1 --rows 10`                                                               |
| Read a Paylink                            | `paylinks:get --id <paylinkId>`                                                                  |
| Create a Paylink                          | `paylinks:create --json paylink.json`                                                            |
| Disable a Paylink                         | `paylinks:disable --id <paylinkId> --confirm`                                                    |
| Create a Checkout Session                 | `checkout-sessions:create --json checkout-session.json --idempotency-key checkout_order_1042_v1` |
| Read a Checkout Session                   | `checkout-sessions:get --id <checkoutSessionId>`                                                 |
| Create a public payment invoice           | `payments:create --json payment.json`                                                            |
| Read payment status                       | `payments:status --id <paymentId>`                                                               |
| List webhook endpoints                    | `webhooks:list`                                                                                  |
| Create an endpoint                        | `webhooks:add --name Production --url https://example.com/api/yolfi/webhook --adapter NONE`      |
| Update an endpoint                        | `webhooks:update --id <endpointId> --json endpoint.json`                                         |
| Rotate an endpoint signing secret         | `webhooks:rotate-secret --id <endpointId> --confirm`                                             |
| Remove an endpoint                        | `webhooks:remove --id <endpointId> --confirm`                                                    |

Prefix each command with `npx -y @yolfi/agent`. `webhooks:configure` remains an alias for endpoint creation. List endpoints before creating another; `NONE`, `STRIPE`, and `LEMON_SQUEEZY` are supported adapter values. The `--confirm` flags acknowledge deliberately requested destructive operations; they are not a substitute for owner authorization.

Request files use the corresponding HTTP request fields:

* [Paylink creation and editing](/en/paylinks/api-reference)
* [Checkout Sessions](/en/checkout/api-reference)
* [Organization and settlement updates](/en/accept-payments/settlement-wallet#http-configuration)
* [Webhook endpoints](/en/webhooks#endpoint-management-api)
* [Public payment invoices](/en/accept-payments#public-payment-api)

For a fixed-price link, for example, save this as `paylink.json`:

```json
{
  "name": "Premium download",
  "type": "ONE_TIME",
  "price": "29.00",
  "currency": "USD",
  "collectEmail": true
}
```

Creating the link returns `data.id`; its hosted URL is `https://pay.yolfi.com/{paylinkId}`. For Checkout Sessions, reuse the same idempotency key and request after a timeout rather than creating another order attempt.

Webhook verification [#webhook-verification]

CLI endpoint creation and secret rotation save the returned signing secret in the protected local profile and return `signingSecretStored: true` instead of printing the secret. Verify a raw payload with its saved endpoint secret:

```bash
npx -y @yolfi/agent webhooks:verify \
  --endpoint-id <endpointId> \
  --payload payload.json \
  --signature <signature-header>
```

`payload.json` must contain the original request bytes, not parsed and reserialized JSON. You can alternatively supply `YOLFI_WEBHOOK_SECRET` through your environment. A fixture payload and fixture secret are sufficient for local unit checks; they do not prove a live payment occurred.

The local profile does not configure your deployed webhook receiver. Transfer the saved secret through the deployment's secret manager without logging it. A local Node.js provisioning script can use the package's `readWebhookSigningSecret(endpointId)` helper to read it and pass it directly to the secret manager. Never use `YOLFI_API_KEY` as the webhook signing secret. See [signature verification](/en/webhooks/webhook-signatures).

The package also exposes a JavaScript verification helper:

```js
import { verifyWebhookSignature } from '@yolfi/agent';

const valid = verifyWebhookSignature(rawBody, signature, process.env.YOLFI_WEBHOOK_SECRET);
```

Always verify the raw request body. Do not parse and re-stringify JSON before verification.

Environment variables [#environment-variables]

| Name                   | Purpose                                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `YOLFI_API_KEY`        | Explicit organization-key fallback for private API operations. Browser setup stores a dedicated credential instead. |
| `YOLFI_CONFIG_HOME`    | Optional isolated credential and signing-secret profile; defaults to `~/.yolfi`.                                    |
| `YOLFI_PAY_BASE_URL`   | Hosted payment URL base; defaults to `https://pay.yolfi.com`.                                                       |
| `YOLFI_WEBHOOK_SECRET` | Optional endpoint-specific verification secret supplied by secret storage.                                          |

Public Paylink checkout and public payment-status requests do not require an application API key. A deployed backend making private Checkout Session calls needs a separately configured server credential; CLI authorization does not automatically configure deployment secrets.

Package and examples [#package-and-examples]

* [npm package](https://www.npmjs.com/package/@yolfi/agent)
* [Public package source and examples](https://github.com/yolfinance/yolfi-agent)
* [Yolfi Agent Kit](https://yolfi.com/ai-agent-kit)
* [AI Agent Payment Integration API](https://yolfi.com/blog/ai-agent-payment-integration-api)

Earlier reference links [#earlier-reference-links]

<span id="cli-quickstart" />

<span id="local-cli-and-mcp-setup" />

[CLI browser authentication](#browser-authentication).

<span id="cli-commands" />

[Command reference](#command-reference).

<span id="manual-api-key-setup" />

[Non-interactive authentication](#non-interactive-authentication).

<span id="choose-remote-or-local-mcp" />

<span id="remote-mcp-setup" />

<span id="generic-local-mcp-configuration" />

[Agent connection selection and MCP setup](/en/agent-kit/connections#choose-a-connection).

<span id="codex" />

[Codex MCP setup](/en/agent-kit/connections#codex).

<span id="claude-code" />

[Claude Code MCP setup](/en/agent-kit/connections#claude-code).

<span id="claude-web-desktop-and-mobile" />

<span id="chatgpt" />

<span id="cursor" />

<span id="hermes" />

<span id="openclaw-and-other-local-agents" />

[Other MCP hosts](/en/agent-kit/connections#other-mcp-hosts).

<span id="email-confirmed-signup-for-a-new-user" />

[New account signup](#new-account-signup).

<span id="verify-the-connection-in-the-agent" />

[Connection verification and recovery](/en/agent-kit/connections#verification-and-recovery).

<span id="agent-workflow" />

<span id="safety-rules" />

[Canonical agent workflow](/en/agent-kit#instructions-for-the-agent).

<span id="knowledge-resources-and-guided-prompts" />

[MCP resources and prompts](/en/agent-kit/connections#mcp-resources-and-prompts).

<span id="endpoint-adapter-matrix" />

[HTTP endpoint reference](/en/api#api-entry-points).

<span id="related-resources" />

[Connect with AI](/en/agent-kit) or browse the [HTTP API](/en/api).