> 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.md).

# Doma CLI

The Doma CLI (`@doma-protocol/cli`, distributed as the `doma` binary) is the local TypeScript tool that executes everything skills decide on: token swaps, marketplace orders, DNS edits, bridges, subdomain operations, and authentication. It is designed to be both human-driven (interactive prompts, pretty output) and AI-driven (`--quiet --format json` for clean machine-readable I/O).

## Install

```bash
npm install -g @doma-protocol/cli
doma --version
```

Requires **Node.js ≥ 20**.

## Configure

Configuration is stored in `~/.doma/config.json`. Set values either via the CLI:

```bash
doma config set <key> <value>
```

Or by editing `~/.doma/config.json` directly:

```json
{
  "privateKey": "<keychain-on-macos>",
  "apiKey": "<your-doma-api-key>",
  "chainId": 97477,
  "testnet": false,
  "walletMode": "private-key"
}
```

### Config keys

| Key             | Description                                                        | Default                |
| --------------- | ------------------------------------------------------------------ | ---------------------- |
| `privateKey`    | Wallet private key (required for transactions in private-key mode) | (none)                 |
| `apiKey`        | API key for the Doma GraphQL endpoint                              | (none)                 |
| `apiUrl`        | Override the API endpoint (`--testnet` flag overrides this)        | (none)                 |
| `routingApiUrl` | Override the routing API endpoint                                  | (none)                 |
| `chainId`       | Default chain ID for writes                                        | `97477` (Doma mainnet) |
| `testnet`       | Use Doma testnet instead of mainnet                                | `false`                |
| `walletMode`    | `agent` (Privy delegated) or `private-key` (local)                 | `private-key`          |

### Environment variable overrides

Env vars take precedence over `~/.doma/config.json`:

| Config key      | Env var                |
| --------------- | ---------------------- |
| `privateKey`    | `DOMA_PRIVATE_KEY`     |
| `apiKey`        | `DOMA_API_KEY`         |
| `apiUrl`        | `DOMA_API_URL`         |
| `routingApiUrl` | `DOMA_ROUTING_API_URL` |
| `chainId`       | `DOMA_CHAIN_ID`        |
| `testnet`       | `DOMA_TESTNET`         |

`walletMode` is config-only (no env-var override), change it via `doma config set walletMode <agent|private-key>`.

### macOS Keychain

On macOS, `doma config set privateKey` stores the key in the system Keychain rather than `config.json`. To force plain-text storage instead:

```bash
doma config set privateKey 0x… --plaintext
```

On Linux and Windows, `config.json` is used unconditionally.

{% hint style="warning" %}
Never paste a private key into chat or commit it to a repo. Use a dedicated wallet for testing and rotate it after.
{% endhint %}

## Network selection

Use `--testnet` on any command to target Doma Testnet:

```bash
doma --testnet token <token-name>
doma --testnet swap USDC <token-name> 10
```

Or persist the choice:

```bash
doma config set testnet true
```

## Supported chains

| Chain        | Chain ID |
| ------------ | -------- |
| Doma Mainnet | `97477`  |
| Doma Testnet | `97476`  |
| Ethereum     | `1`      |
| Base         | `8453`   |

## Sponsored gas

DNS and nameserver writes on the Doma chain use **sponsored gas** via ERC-4337 + EIP-7702. You don't need ETH on Doma chain to set DNS records or rotate nameservers. Other operations (swaps, bridges, marketplace transactions) require gas in the chain's native token.

## What's next

* [Wallet Modes](/agentic-commerce/doma-cli/wallet-modes.md): choose between agent (Privy) and private-key signing.
* [Commands](/agentic-commerce/doma-cli/commands.md): full per-command reference with examples.


---

# 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.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.