> For the complete documentation index, see [llms.txt](https://docs.doma.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.doma.xyz/agentic-commerce/doma-cli/wallet-modes.md).

# Wallet Modes

The Doma CLI signs writes in one of two modes. The mode you pick determines **what holds the signing authority**, **what scope it has**, and **how revocable it is**.

## The two modes

| Mode                      | Signs via                                     | Setup                               | Spend authority                           |
| ------------------------- | --------------------------------------------- | ----------------------------------- | ----------------------------------------- |
| `agent` (Privy delegated) | Doma launchpad → Privy delegated signer       | `doma auth login` (browser consent) | USD-capped, scoped to Doma chains         |
| `private-key` (default)   | Local raw key in `~/.doma/config.json` or env | `export DOMA_PRIVATE_KEY=0x…`       | Unbounded, limited only by wallet balance |

Both modes are first-class. The transactional flow is byte-identical; only the authentication setup and revocation story differ.

## Which mode should I pick?

Find your situation in the table:

| Situation                                               | Pick          |
| ------------------------------------------------------- | ------------- |
| CI, cron, or any non-interactive run                    | `private-key` |
| Need a USD spend cap or infra-enforced chain allowlist  | `agent`       |
| Personal dev box, want hands-off browser consent        | `agent`       |
| Personal dev box, prefer a dedicated test wallet        | `private-key` |
| Production server with a secrets manager                | `private-key` |
| Already use Doma in your browser, want one-command auth | `agent`       |

When in doubt: **start with `private-key` on testnet**, switch to `agent` for any wallet that holds value worth protecting.

## Setting up agent mode

Requires Doma CLI **≥ 0.5.0**. The CLI runtime-detects support via `doma auth --help` (older versions return non-zero).

Agent mode is supported on both **Doma Mainnet** (chain `97477`) and **Doma Testnet** (chain `97476`). The active network is whichever your config / `--testnet` flag selects; `doma auth login` mints a session for that network. To use both networks, run `doma auth login` once per network.

```bash
doma auth login
```

The CLI prints a localhost URL. Open it in your browser. You'll see a Privy-hosted consent screen. Review the wallet being authorized, the allowed chains and RPC methods, and the spend ceiling (default `$200 USD`), then confirm. Once approved, the CLI prints `Authorized.` and writes a session JWT to `~/.doma/credentials.json` (mode `0600`).

Persist the choice so future commands use agent mode by default:

```bash
doma config set walletMode agent
```

{% hint style="info" %}
The browser consent screen is the **actual authorization moment**. The CLI does not prompt again. If you change your mind, click **Cancel** in the browser and the session is never minted.
{% endhint %}

## Setting up private-key mode

Set the key as an environment variable in your shell:

```bash
export DOMA_PRIVATE_KEY=0x<64-hex-chars>
```

Or persist it via the CLI (macOS uses Keychain by default, see [Install & Configure](/agentic-commerce/doma-cli.md#macos-keychain)):

```bash
doma config set privateKey 0x<64-hex-chars>
```

Then mark the mode explicitly (this is the default, but explicit beats implicit):

```bash
doma config set walletMode private-key
```

{% hint style="warning" %}
Use a dedicated wallet for the CLI. The key on disk is fully empowered: anything that can read the file can drain the wallet. Don't reuse a personal hardware-wallet-derived key here.
{% endhint %}

## Switching modes

```bash
doma config set walletMode agent          # switch to agent
doma config set walletMode private-key    # switch back
```

The CLI uses whichever mode is active at command time. Read commands (`token`, `quote`, `balance`) work in either mode without auth.

## Revoking an agent session

```bash
doma auth revoke
```

This calls Privy to detach the agent's authorization key from your wallet, deletes `~/.doma/credentials.json`, and clears `walletMode`. Future writes require a fresh `doma auth login`.

You can also revoke from the launchpad's "Authorized agents" panel at any time. Useful if your machine is lost.

## Checking session status

```bash
doma auth status
```

Output:

```
Mode:        agent
Wallet:      0xabc…123
Session:     active
Expires:     <timestamp>
Spend cap:   $200 (used: $7.32)
```

## Trade-offs at a glance

|                               | `agent`                      | `private-key`          |
| ----------------------------- | ---------------------------- | ---------------------- |
| Key on disk                   | No (Privy HSM)               | Yes                    |
| Spend cap                     | Hard-enforced ($200 default) | None                   |
| Chain allowlist               | Doma chains only             | All chains             |
| Revoke from another machine   | Yes (launchpad UI)           | Need to rotate the key |
| Works in CI / non-interactive | No (needs browser consent)   | Yes                    |
| Available since               | CLI 0.5.0                    | All versions           |

## What's next

* [Commands](/agentic-commerce/doma-cli/commands.md): full reference of what the CLI can do.
* [Agentic Wallet](/agentic-commerce/agentic-wallet.md): deeper architectural look at the Privy delegated signer.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.doma.xyz/agentic-commerce/doma-cli/wallet-modes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.