> ## Documentation Index
> Fetch the complete documentation index at: https://docs.privy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent CLI

**The Privy Agent CLI gives agents a simple way to spin up, fund, and manage wallets without any integration work. It pairs with an [Agent Sandbox](https://agents.privy.io/) that lets users track agent spending activity, manage funds, and stay in control.** The sandbox CLI (`@privy-io/agent-wallet-cli`) enables authentication, funding, and transactions directly from assistants like OpenClaw, Claude Code, and more.

Go to [agents.privy.io](https://agents.privy.io) to track agent activity and spend in the agent sandbox.

## Getting started

<Tabs>
  <Tab title="For humans">
    <Steps>
      <Step title="Visit the agent sandbox">
        Go to [agents.privy.io](https://agents.privy.io) to create an account, view wallets, and manage agent activity.
      </Step>

      <Step title="Install the CLI">
        Install the agent sandbox CLI globally:

        ```bash theme={"system"}
        npm install -g @privy-io/agent-wallet-cli
        ```

        Or run it directly with `npx`:

        ```bash theme={"system"}
        npx @privy-io/agent-wallet-cli login
        ```
      </Step>

      <Step title="Log in">
        Start the authentication flow. The CLI displays a verification URL and a short code, then waits for approval.

        ```bash theme={"system"}
        privy-agent-wallets login
        ```

        Open the URL in a browser and sign in to the agent sandbox. Enter the code shown in the terminal to approve agent access. The CLI automatically completes once approval is confirmed.
      </Step>

      <Step title="Fund wallets">
        Open the agent sandbox in a browser to add funds via onramp:

        ```bash theme={"system"}
        privy-agent-wallets fund
        ```

        The agent sandbox at [agents.privy.io](https://agents.privy.io) provides a visual interface to view balances, review transaction history, and onramp funds into the wallet.
      </Step>

      <Step title="View wallets">
        List the Ethereum and Solana wallet addresses linked to the session:

        ```bash theme={"system"}
        privy-agent-wallets list-wallets
        ```

        Output:

        ```
        Ethereum:  0x1a2b...3c4d  (wallet_id_xxx)
        Solana:    7hQ5p...mN9r   (wallet_id_yyy)
        ```
      </Step>

      <Step title="Send transactions">
        Use the `rpc` command to sign messages and send transactions. Pass the RPC body as JSON:

        ```bash theme={"system"}
        privy-agent-wallets rpc --json '{"method": "eth_sendTransaction", "params": {"to": "0xRecipient", "value": "0.01"}}'
        ```

        The body can also be piped from stdin:

        ```bash theme={"system"}
        echo '{"method": "personal_sign", "params": {"message": "hello"}}' | privy-agent-wallets rpc
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="For agents">
    ```
    Set up https://agents.privy.io/skill.md
    ```
  </Tab>
</Tabs>

## Supported RPC methods

### Ethereum

| Method                      | Description                      |
| --------------------------- | -------------------------------- |
| `personal_sign`             | Sign a plaintext message         |
| `eth_sendTransaction`       | Send a transaction               |
| `eth_signTransaction`       | Sign without broadcasting        |
| `eth_signTypedData_v4`      | Sign EIP-712 typed data          |
| `secp256k1_sign`            | Raw secp256k1 signature          |
| `eth_sign7702Authorization` | EIP-7702 authorization           |
| `eth_signUserOperation`     | Sign a user operation (ERC-4337) |

### Solana

| Method                   | Description                      |
| ------------------------ | -------------------------------- |
| `signTransaction`        | Sign a Solana transaction        |
| `signAndSendTransaction` | Sign and broadcast a transaction |
| `signMessage`            | Sign an arbitrary message        |

## Design principles

* **CLI-first distribution**: Agents already execute shell commands. A CLI is the most natural interface for agent-driven wallets.
* **Skill-based discovery**: The [skill file](https://agents.privy.io/skill.md) teaches agents how to authenticate and transact without human guidance beyond the initial login.
* **Browser-based funding**: The human owner retains a visual dashboard to check balances, view transaction history, and onramp funds, keeping the human in control.
* **Cryptographic authorization**: Each transaction uses an ephemeral signing key obtained by exchanging an OAuth access token. The agent is never given the wallet private key or app secret.

## How it works

1. The CLI calls Privy's device authorization endpoint and displays a short verification URL and code.
2. The human visits the URL, signs in through Privy, and approves agent access.
3. The CLI polls until approval is confirmed and stores the resulting access and refresh tokens in the OS credential manager.
4. For every transaction, the CLI exchanges the access token for an ephemeral signing key, signs the request, and submits it directly to Privy's wallet API. See [Authorized wallet access for self-hosted agents](/recipes/agent-integrations/agent-authorization) for the full API flow.

## Session and credential storage

The CLI attempts to use the OS-backed credential manager when available, and otherwise falls back to storing session data in an encrypted file at `~/.privy/session.json`. It is the responsibility of the agent or user to install any required prerequisites for the OS credential manager.

| Platform | Credential manager            | Prerequisites                                          |
| -------- | ----------------------------- | ------------------------------------------------------ |
| macOS    | Keychain (`security` CLI)     | None (available by default)                            |
| Linux    | libsecret (`secret-tool` CLI) | `sudo apt install -y libsecret-tools` (Debian/Ubuntu)  |
| Windows  | PowerShell SecretManagement   | `Install-Module Microsoft.PowerShell.SecretManagement` |

When the OS credential manager is not available (e.g., Docker containers, headless servers, or missing prerequisites), the CLI falls back to an encrypted file at `~/.privy/session.json`. This file is not portable between machines.

Each session contains:

* The app ID for the Privy agent wallet app
* Ethereum and Solana wallet IDs and addresses
* The OAuth access token and refresh token
* A creation timestamp

Sessions remain active for up to 30 days. The access token refreshes automatically on each transaction; the refresh token rotates on each use. To end a session early:

```bash theme={"system"}
privy-agent-wallets logout
```

Users can always revoke agent access to their wallet via the agent sandbox at [agents.privy.io/manage](https://agents.privy.io/manage).

## Learn more

<CardGroup cols={2}>
  <Card title="Agent CLI" href="https://agents.privy.io" arrow>
    Track agent activity, view balances, and manage wallets.
  </Card>

  <Card title="Agentic wallets" href="/recipes/agent-integrations/agentic-wallets" arrow>
    Build developer-controlled agent wallets with policy guardrails.
  </Card>

  <Card title="x402 payments" href="/recipes/agent-integrations/x402" arrow>
    Enable HTTP-native payments for APIs and digital content.
  </Card>

  <Card title="MPP integration" href="/recipes/agent-integrations/mpp" arrow>
    Machine-to-machine payments over HTTP with Privy wallets.
  </Card>

  <Card title="Gas sponsorship" href="/wallets/gas-and-asset-management/gas/overview" arrow>
    Sponsor gas fees for agent transactions.
  </Card>

  <Card title="Agent authorization" href="/recipes/agent-integrations/agent-authorization" arrow>
    Let agents from any platform access user wallets in your own Privy app.
  </Card>
</CardGroup>